From 0b6d878fd34d08719b8ed187cb906d001fdde3c8 Mon Sep 17 00:00:00 2001 From: Robert D Anderson Date: Tue, 26 May 2026 13:19:40 -0500 Subject: [PATCH] Remove obsolete topics about XSD coding conventions --- .../base/xsd-coding-attribute-domains.dita | 22 -- .../base/xsd-coding-constraint-modules.dita | 108 ---------- .../base/xsd-coding-doctype-shell.dita | 204 ------------------ .../base/xsd-coding-element-types.dita | 96 --------- .../archSpec/base/xsd-coding-overview.dita | 23 -- .../base/xsd-coding-requirements.ditamap | 13 -- .../base/xsd-coding-structural-modules.dita | 59 ----- .../archSpec/base/xsd-requirements.dita | 8 - 8 files changed, 533 deletions(-) delete mode 100644 specification/archSpec/base/xsd-coding-attribute-domains.dita delete mode 100644 specification/archSpec/base/xsd-coding-constraint-modules.dita delete mode 100644 specification/archSpec/base/xsd-coding-doctype-shell.dita delete mode 100644 specification/archSpec/base/xsd-coding-element-types.dita delete mode 100644 specification/archSpec/base/xsd-coding-overview.dita delete mode 100644 specification/archSpec/base/xsd-coding-requirements.ditamap delete mode 100644 specification/archSpec/base/xsd-coding-structural-modules.dita delete mode 100644 specification/archSpec/base/xsd-requirements.dita diff --git a/specification/archSpec/base/xsd-coding-attribute-domains.dita b/specification/archSpec/base/xsd-coding-attribute-domains.dita deleted file mode 100644 index 22dfbc61..00000000 --- a/specification/archSpec/base/xsd-coding-attribute-domains.dita +++ /dev/null @@ -1,22 +0,0 @@ - - - - XML Schema: Coding requirements for attribute domain modules - An attribute domain vocabulary module declares one new attribute specialized from - either the props or base attribute. - -

-

An attribute domain consists of one file. The file must have a single attribute group - definition that contains the definition of the attribute itself, where the attribute group is - named attnameAtt-d-attribute.

-

For example, the deliveryTarget attribute is defined - with the following attribute - group:<xs:attributeGroup name="deliveryTargetAtt-d-attribute"> - <xs:attribute name="deliveryTarget" type="xs:string"> - <!-- Documentation for attribute --> - </xs:attribute> -</xs:attributeGroup>

- - - diff --git a/specification/archSpec/base/xsd-coding-constraint-modules.dita b/specification/archSpec/base/xsd-coding-constraint-modules.dita deleted file mode 100644 index 5b279aa7..00000000 --- a/specification/archSpec/base/xsd-coding-constraint-modules.dita +++ /dev/null @@ -1,108 +0,0 @@ - - - - XML Schema: Coding requirements for constraint modules - A structural constraint module defines the constraints for a map or topic element type. - A domain constraint module defines the constraints for an element or attribute - domain. - - - - coding - requirementsXSDconstraints - constraintsXSDcoding - requirementsexamplesintegrating into - document-type shells - domain constraint modulesXSDcoding - requirementsexamples - file namesXSDdomain constraint - modulesstructural contraint - modules - structural constraint modulesXSDcoding - requirementsexamples - - - - -

-

For each vocabulary module with a content model or attributes to be - constrained, there must be an - xs:redefine element that references the vocabulary module. Within the - xs:redefine element, for each element type content model to be - constrained, an xs:group element is needed with the name - element.content. Also within the - xs:redefine element, for each attribute set to be constrained, an - xs:attributeGroup element is needed with the name - element.attributes. The constrained model is defined - inside of the xs:group or - xs:attributeGroup.

- This means that when adding a constraint module to an existing document-type shell, you - must remove any xs:include elements that refer to the XSD module to - which the redefine is applied. For example, to redefine groups defined in - commonElementsMod.xsd, you must remove any - xs:include reference to - commonElementsMod.xsd. -

Because the constraint module includes the module that it modifies, only one constraint - module can be used per vocabulary module (otherwise the module being constrained would be - included multiple times). If multiple constraint modules are needed for a single vocabulary - module, they must be combined into a single XSD module. For example, when combining existing - constraint modules for p and div, a single - module must be created that combines the xs:group and - xs:attributeGroup constraints from existing modules inside a single - xs:redefine reference to - commonElementsMod.xsd.

-

When constraining a list of elements provided by a domain, there must be a group that lists the subset of domain elements in a constraints module. The - group name SHOULD be named - "qualifierdomain-c-tagname" where - qualifier is a description for the constraint - module, domain is the name of the domain, map, or topic being - constrained, and tagname is the name of the extension element being - restricted.

- - Example: Structural constraint module -

The following code fragment shows how the - topic element can be constrained to disallow the - body element. This xs:redefine element - is located in a constraint module that references the file topicMod.xsd, which means that a document-type shell using this constraint - would reference this module instead of referencing topicMod.xsd (it would not reference both).

- <xs:redefine schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:topicMod.xsd:1.2"> - <xs:group name="topic.content"> - <xs:sequence> - <xs:sequence> - <xs:group ref="title"/> - <xs:group ref="titlealts" minOccurs="0"/> - <xs:choice minOccurs="1" > - <xs:group ref="shortdesc" /> - <xs:group ref="abstract" /> - </xs:choice> - <xs:group ref="prolog" minOccurs="0"/> - <!--<xs:group ref="body" minOccurs="0"/>--> - <xs:group ref="related-links" minOccurs="0"/> - <xs:group ref="topic-info-types" minOccurs="0" - maxOccurs="unbounded"/> - </xs:sequence> - </xs:sequence> - </xs:group> -</xs:redefine> -

For a more complete example, see strictTaskbodyConstraintMod.xsd, - delivered with the DITA 1.3 grammar files.

- - - Example: Domain constraint module -

The following code fragment shows how the highlighting - domain can be constrained to limit the elements that are available in the domain to only - b and i.

- - - - - -]]> - - - diff --git a/specification/archSpec/base/xsd-coding-doctype-shell.dita b/specification/archSpec/base/xsd-coding-doctype-shell.dita deleted file mode 100644 index 8e983173..00000000 --- a/specification/archSpec/base/xsd-coding-doctype-shell.dita +++ /dev/null @@ -1,204 +0,0 @@ - - - - XML Schema: Coding requirements for document-type shells - XSD-based document-type shells are organized into sections; each section contains a - specific type of declaration. - - - -

XSD-based document-type shells use the XML Schema redefine feature - (xs:redefine) to override base group definitions for content models - and attribute lists. This facility is analogous to the parameter entities that are used for - DTD-based document-type shells. Unlike DTD parameter entities, an - xs:redefine both includes the XSD file that it redefines and holds - the redefinition that is applied to the groups in the included XSD file. Thus, for XSD files - that define groups, the file can be included using xs:include if it - is used without modification or using xs:redefine if any of its - groups are redefined.

- -

XSD-based document-type shells contain the following sections.

-
- -
Topic or map domains
-
-

For each element or attribute domain that is integrated into the document-type shell, - this section uses an xs:include element to include the XSD - module for that domain.

-

For - example:<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:deliveryTargetAttDomain.xsd:1.3"/> -<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:highlightDomain.xsd:1.3"/> -<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:indexingDomain.xsd:1.3"/>

-
- - -
Group definitions
-
-

The group inclusion section contains xs:include or - xs:redefine references for element groups. The group files - define named groups that are used to integrate domain-provided element and attribute - types into base content models. There is one group file for each structural type; domain - files can also have group files.

-

For both map and topic shells, this section also must include or redefine the following - groups; it must also include the module file for each group:

-
    -
  • Common element group (commonElementGrp.xsd and - commonElementMod.xsd)
    • -
  • Metadata declaration group (metaDeclGrp.xsd and - metaDeclMod.xsd)
    • -
  • Table model group (tblDeclGrp.xsd and - tblDeclMod.xsd)
    • -
-

The group files and the module files for base groups can be specified in any order.

-

For each element extended by one or more domains, the document-type shell must redefine - the model group for the element to a list of alternatives including the literal name of - the element and the element extension model group from each domain that is providing - specializations. To integrate a new domain in the document-type shell, use the schema - xs:redefine mechanism to import a group definition file while - redefining and extending an element from that group. The model group requires a - reference to itself to extend the base model group.

-

For each attribute extended by one or more domains, the document-type shell must - redefine the attribute extension model group for the attribute to a list of alternatives - including the literal name of the attribute and the attribute extension model group from - each domain that is providing specializations. To integrate a new attribute domain in - the document-type shell, use the schema xs:redefine mechanism - to import the commonElementGrp.xsd group file while redefining and - extending the base attribute.

-

For example, the following portion of a document-type shell - includes the common metadata module and then adds a domain extension of the - metadata element from the metadata group. It also extends the - props attribute from the common element module to add the specialized - attribute - deliveryTarget.<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:metaDeclMod.xsd:1.3"/> -<!-- ... --> -<xs:redefine schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:commonElementGrp.xsd:1.3"> - <!-- ...Redefinition of any elements in common module --> - <xs:attributeGroup name="props-attribute-extensions"> - <xs:attributeGroup ref="props-attribute-extensions"/> - <xs:attributeGroup ref="deliveryTargetAtt-d-attribute"/> - </xs:attributeGroup> -</xs:redefine> -<xs:redefine schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:metaDeclGrp.xsd:1.3"> - <xs:group name="metadata"> - <xs:choice> - <xs:group ref="metadata"/> - <xs:group ref="relmgmt-d-metadata"/> - </xs:choice> - </xs:group> -</xs:redefine>>

-
- - -
Module inclusions
-
-

The module inclusion section includes the module XSD files for structural types used in - the shell. These must be placed after the group and files and redefinitions.

-

This section must also include any other module XSD - files required by the topic or map types. For example, if a - troubleshooting specialization is specialized from topic but includes elements from - task, then the task structural module must be included in the document shell.

-

If a structural type is constrained, that constraint will be included rather than the - module itself; for example, in a document-type shell that constrains the task - specialization, the task constraint module will be included rather than the task - module.

-

For example, the following portion of a document-type shell - includes the structural modules for topic and - concept:.<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:topicMod.xsd:1.3"/> -<xs:include schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:conceptMod.xsd:1.3"/>

-
- - - -
Domains attribute declaration
-
-

The domains attribute declaration section declares the - domains attribute for the shell. It does this by redefining the - domains-att group, adding one token for each vocabulary and - constraint module integrated by the shell. See for details on the syntax - for domains tokens.

-

For example, the following sample defines the - domains-att to include the OASIS domains for map group, indexing, and - deliveryTarget:<xs:attributeGroup name="domains-att"> - <xs:attribute name="domains" type="xs:string" - default="(map mapgroup-d) (topic indexing-d) a(props deliveryTarget)"/> -</xs:attributeGroup>

-
- - -
Info-types definition
-
-

This section defines whether and how topics can nest by redefining the - info-types group. That group is referenced but undefined in the - module files, so it must be defined in the shell. Topic testing can be disallowed by - setting the info-types group to reference the - no-topic-nesting element, with the maxOccurs - and minOccurs attributes each set to "0".

-

Optionally, topictype-info-types groups can be - redefined to provide more fine grained control of nesting with specialized topic types. - As with domain extensions, this is done by redefining the group while importing the - module that defines the group.

-

For example, in the concept vocabulary module delivered by OASIS, - the concept-info-types group controls which topics can nest inside the - concept element. That group is defined as including - concept plus the info-types group. The - following examples demonstrate how to control topic nesting within - concept using a document-type shell.

-
    -
  • To have concept only nest itself, the - info-types group must be defined so that it does not add any - additional - topics:<xs:group name="info-types"> - <xs:choice> - <xs:element ref="no-topic-nesting" maxOccurs="0" minOccurs="0"/> - </xs:choice> -</xs:group>
    • -
  • In order to turn off topic nesting entirely within concept, - the concept-info-types group must be redefined to remove - concept, and the info-types group must be - defined as - above:<xs:group name="info-types"> - <xs:choice> - <xs:element ref="no-topic-nesting" maxOccurs="0" minOccurs="0"/> - </xs:choice> -</xs:group> - -<xs:redefine schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:conceptMod.xsd:1.3" > - <xs:group name="concept-info-types"> - <xs:choice> - <xs:group ref="info-types"/> - </xs:choice> - </xs:group> -</xs:redefine>
    • -
  • In order to add topic as a nesting topic within - concept, define info-types to allow any - number of topic - elements:<xs:group name="info-types"> - <xs:choice> - <xs:element ref="topic" maxOccurs="unbounded" minOccurs="0"/> - </xs:choice> -</xs:group>
    • -
  • With the preceding example, concept is allowed to nest - either concept or topic. In order to - make topic the only valid child topic, the - concept-info-types must be redefined as - follows:<xs:redefine schemaLocation="urn:pubid:oasis:names:tc:dita:xsd:conceptMod.xsd:1.3" > - <xs:group name="concept-info-types"> - <xs:choice> - <xs:group ref="info-types"/> - </xs:choice> - </xs:group> -</xs:redefine>
    • -
-
- -
- - diff --git a/specification/archSpec/base/xsd-coding-element-types.dita b/specification/archSpec/base/xsd-coding-element-types.dita deleted file mode 100644 index bcfb1678..00000000 --- a/specification/archSpec/base/xsd-coding-element-types.dita +++ /dev/null @@ -1,96 +0,0 @@ - - - - XML Schema: Coding requirements for element type declarations - Structural and domain vocabulary modules have the same XSD coding requirements for - element type declarations. - -
- Element definitions -

A structural or domain vocabulary module must contain a declaration for each specialized - element type named by the module. While the XSD standard allows content models to refer to - undeclared element types, all element types named in content models within a vocabulary - module must have an xs:element declaration, either in the - vocabulary module, in a base module from which the vocabulary module is specialized, or in a - required domain module.

-

Domain modules consist of a single XSD document. Structural modules consist of two modules; - one module contains all element name groups, and the other contains all other declarations - for the module.

-

For each element type that is declared in the vocabulary module, the following set of - groups and declarations must be used to define the content model and attributes for the - element type. These groups are typically placed together within the module for clarity.

-
    -
  • For each element type declared in the vocabulary module there must be an - xs:group element whose name is the element type name, and whose - one member is a reference to the element type. This element name group provides a layer of - abstraction that facilitates redefinition. A document-type shell can redefine an element - group to add domain-specialized elements or to replace a base element type with one or - more specializations of that type.
    • -
  • Each element type must have a corresponding content model group named - tagname.content. The value of the group is the complete - content model definition; the content model group can be overridden in constraint modules - to further constrain the content model.
    • -
  • Each element type must have a corresponding attribute group named - tagname.attributes. The value of the group is the complete - attribute set for the element type, except for the class attribute. Like - the content model, this group can be overridden in a constraint module to constrain the - attribute set.
    • -
  • Each element type must have a complex type definition named - tagname.class, which references the - tagname.content and - tagname.attributes groups.
    • -
  • Each element type must have an xs:element declaration named - tagname, that uses as its type the - tagname.class complex type and extends that - complex type to add the class attribute for the element.
    • -
-

For example, the following set of declarations shows each of the - required groups and definitions for the specialized codeph - element.<xs:group name="codeph"> - <xs:sequence> - <xs:choice> - <xs:element ref="codeph"/> - </xs:choice> - </xs:sequence> -</xs:group> - -<xs:group name="codeph.content"> - <xs:sequence> - <xs:choice minOccurs="0" maxOccurs="unbounded"> - <xs:group ref="basic.ph.notm"/> - <xs:group ref="data.elements.incl"/> - <xs:group ref="draft-comment"/> - <xs:group ref="foreign"/> - <xs:group ref="required-cleanup"/> - </xs:choice> - </xs:sequence> -</xs:group> - -<xs:attributeGroup name="codeph.attributes"> - <xs:attributeGroup ref="univ-atts"/> -</xs:attributeGroup> - -<xs:complexType name="codeph.class" mixed="true"> - <xs:sequence> - <xs:group ref="codeph.content"/> - </xs:sequence> - <xs:attributeGroup ref="codeph.attributes"/> -</xs:complexType> - -<xs:element name="codeph"> - <xs:annotation> - <xs:documentation> <!-- documentation for codeph --> </xs:documentation> - </xs:annotation> - <xs:complexType> - <xs:complexContent> - <xs:extension base="codeph.class"> - <xs:attribute ref="class" default="+ topic/ph pr-d/codeph "/> - </xs:extension> - </xs:complexContent> - </xs:complexType> -</xs:element>

-
- - - diff --git a/specification/archSpec/base/xsd-coding-overview.dita b/specification/archSpec/base/xsd-coding-overview.dita deleted file mode 100644 index b1d7c543..00000000 --- a/specification/archSpec/base/xsd-coding-overview.dita +++ /dev/null @@ -1,23 +0,0 @@ - - - - XML Schema: Overview and limitations of coding requirements - DITA coding practices for XML Schema rely on the XSD redefine facility in order to - implement specializations or constraints. However, limitations in the redefine facility can - present problems for some DITA modules implemented in XML Schema. - -

Specializations and constraints in XML Schema are implemented using the XSD - xs:redefine facility. However, this facility does not allow sequence - groups to be directly constrained. Thus, to support both specialization and constraints, it might - be necessary to refactor content models into named groups that can be redefined. In order to keep - the XSD, RELAX NG, and DTD implementations as consistent as possible, the DITA Technical - Committee only refactored those content models that were required for OASIS-provided grammars, the strict task body and machinery-industry task. The other DITA - content models distributed by OASIS have not been refactored.

-

You MAY modify OASIS-provided XSD modules - to refactor content models if required by your constraint. You SHOULD notify the DITA Technical Committee (TC) of your constraint - requirements, so the TC can consider adding the required refactoring to the OASIS-provided - XSDs.

- - diff --git a/specification/archSpec/base/xsd-coding-requirements.ditamap b/specification/archSpec/base/xsd-coding-requirements.ditamap deleted file mode 100644 index 1f511da4..00000000 --- a/specification/archSpec/base/xsd-coding-requirements.ditamap +++ /dev/null @@ -1,13 +0,0 @@ - - - - XSD coding requirements - - - - - - - - - diff --git a/specification/archSpec/base/xsd-coding-structural-modules.dita b/specification/archSpec/base/xsd-coding-structural-modules.dita deleted file mode 100644 index 3b3cf81a..00000000 --- a/specification/archSpec/base/xsd-coding-structural-modules.dita +++ /dev/null @@ -1,59 +0,0 @@ - - - - XML Schema: Coding requirements for structural modules - An XSD structural module declares a top-level map or topic type. It is implemented as a - pair of XSD documents, one that defines groups used to integrate and override the type and one - that defines the element types specific to the type. - -

-

- Module files -

A structural vocabulary module has two files:

-
    -
  • A module schema document.
    • -
  • A module group definition schema document.
    • -
-
-
- Required topic and map element attributes -

The root element for a structural type must reference the DITAArchVersion - attribute and the domains attribute. These attributes give processors a - reliable way to check the architecture version and look up the list of domains available in - the document type. The attributes are referenced as in the following example:

- <xs:attributeGroup name="concept.attributes"> - <!-- Various other attributes --> - <xs:attribute ref="ditaarch:DITAArchVersion"/> - <xs:attributeGroup ref="domains-att"/> -</xs:attributeGroup> -
-
- Controlling nesting in topic types -

For topic modules, the last position in the content model is typically a reference to the - topictype-info-types group. Document types shells - can control how topics are allowed to nest by redefining the group. If topic nesting is hard - coded in the structural module, and cannot be modified from the document-type shell, the - topictype-info-types group is not needed.

-

For example, the vocabulary module for the - concept structural type uses the group - concept-info-types; this group is given a default value, and then - referenced from the content model for the concept element - type:<xs:group name="concept-info-types"> - <xs:choice> - <xs:group ref="concept"/> - <xs:group ref="info-types"/> - </xs:choice> -</xs:group> - -<xs:group name="concept.content"> - <xs:sequence> - <xs:group ref="title"/> - <!-- ...other elements, such as shortdesc and body, and then... --> - <xs:group ref="related-links" minOccurs="0"/> - <xs:group ref="concept-info-types" minOccurs="0" maxOccurs="unbounded"/> - </xs:sequence> -</xs:group>

-
- - diff --git a/specification/archSpec/base/xsd-requirements.dita b/specification/archSpec/base/xsd-requirements.dita deleted file mode 100644 index 1ba862e1..00000000 --- a/specification/archSpec/base/xsd-requirements.dita +++ /dev/null @@ -1,8 +0,0 @@ - - - - XML Schema coding requirements - This section explains how to implement XML Schema (XSD) based document-type shells, - specializations, and constraints. - -