spec/src/main/asciidoc/appC-normative_schema.adoc

//
// Copyright (c) 2020 Contributors to the Eclipse Foundation
//

[appendix]
== Normative Binding Schema Syntax

=== XML Binding Schema

Online version of XML Binding Schema is available at `https://jakarta.ee/xml/ns/jaxb/bindingschema_3_0.xsd`.

[source,xml]
----
<xs:schema
   targetNamespace = "https://jakarta.ee/xml/ns/jaxb"
   xmlns:jaxb = "https://jakarta.ee/xml/ns/jaxb"
   xmlns:xs = "http://www.w3.org/2001/XMLSchema"
   elementFormDefault = "qualified"
   attributeFormDefault = "unqualified">
  <xs:annotation>
    <xs:documentation>
      This is the XML Schema for the Jakarta XML Binding binding
      customization descriptor.
      All binding customization descriptors must indicate
      the descriptor schema by using the Jakarta XML Binding namespace:

      https://jakarta.ee/xml/ns/jaxb

      and by indicating the version of the schema by
      using the version element as shown below:

        <bindings xmlns="https://jakarta.ee/xml/ns/jaxb"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="https://jakarta.ee/xml/ns/jaxb
              https://jakarta.ee/xml/ns/jaxb/bindingschema_3_0.xsd"
          version="3.0">
          ...
        </bindings>

      The instance documents may indicate the published version of
      the schema using the xsi:schemaLocation attribute for Jakarta XML Binding
      namespace with the following location:

      https://jakarta.ee/xml/ns/jaxb/bindingschema_3_0.xsd
    </xs:documentation>
  </xs:annotation>
  <xs:group name = "declaration">
    <xs:annotation>
      <xs:documentation>
        Model group that represents a binding declaration. Each new binding
        declaration added to the jaxb namespace that is not restricted to
        globalBindings should be added as a child element to this model group.
      </xs:documentation>
    </xs:annotation>
    <xs:choice>
      <xs:element ref = "jaxb:globalBindings"/>
      <xs:element ref = "jaxb:schemaBindings"/>
      <xs:element ref = "jaxb:class"/>
      <xs:element ref = "jaxb:property"/>
      <xs:element ref = "jaxb:typesafeEnumClass"/>
      <xs:element ref = "jaxb:typesafeEnumMember"/>
      <xs:element ref = "jaxb:javaType"/>
      <xs:element ref = "jaxb:dom"/>
      <xs:element ref = "jaxb:inlineBinaryData"/>
      <xs:any namespace = "##other" processContents = "lax"/>
    </xs:choice>
  </xs:group>
  <xs:attribute name = "version" type="xs:token" >
    <xs:annotation>
      <xs:documentation>
        Used to specify the version of the binding schema on the schema element for
        inline annotations or jaxb:bindings for external binding.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  <xs:attributeGroup name = "propertyAttributes">
      <xs:annotation><xs:documentation>
        Attributes used for property customization. The attribute group can be
        referenced either from the globalBindings declaration or from the
        property declaration. The following defaults are defined by the JAXB
        specification in global scope only. Thus they apply when the
        propertyAttributes group is referenced from the globalBindings declaration
        but not when referenced from the property declaration.
          collectionType            a class that implements java.util.List.
          fixedAttributeAsConstantProperty  false
          enableFailFastCheck        false
          generateIsSetMethod        false
          optionalProperty           wrapper
          generateElementProperty    false
          attachmentRef              default
      </xs:documentation></xs:annotation>
    <xs:attribute name = "collectionType" type="jaxb:referenceCollectionType"/>
    <xs:attribute name = "fixedAttributeAsConstantProperty" type = "xs:boolean"/>
    <xs:attribute name = "enableFailFastCheck" type = "xs:boolean"/>
    <xs:attribute name = "generateIsSetMethod" type = "xs:boolean"/>
    <xs:attribute name = "optionalProperty">
      <xs:simpleType>
        <xs:restriction base="xs:NCName">
          <xs:enumeration value="wrapper"/>
          <xs:enumeration value="primitive"/>
          <xs:enumeration value="isSet"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
    <xs:attribute name = "generateElementProperty" type="xs:boolean"/>
    <xs:attribute name = "attachmentRef">
      <xs:simpleType>
        <xs:restriction base="xs:NCName">
          <xs:enumeration value="resolve"/>
          <xs:enumeration value="doNotResolve"/>
          <xs:enumeration value="default"/>
        </xs:restriction>
      </xs:simpleType>
    </xs:attribute>
  </xs:attributeGroup>
  <xs:attributeGroup name = "XMLNameToJavaIdMappingDefaults">
    <xs:annotation>
      <xs:documentation>Customize XMLNames to Java id mapping
      </xs:documentation>
    </xs:annotation>
    <xs:attribute name = "underscoreBinding" default = "asWordSeparator" type = "jaxb:underscoreBindingType"/>
  </xs:attributeGroup>
  <xs:attributeGroup name = "typesafeEnumClassDefaults">
    <xs:attribute name = "typesafeEnumMemberName" default = "skipGeneration" type = "jaxb:typesafeEnumMemberNameType"/>
    <xs:attribute name = "typesafeEnumBase" default = "xs:string" type = "jaxb:typesafeEnumBaseType"/>
    <xs:attribute name = "typesafeEnumMaxMembers" type="xs:int" default="256"/>
  </xs:attributeGroup>
  <xs:element name = "globalBindings">
    <xs:annotation>
      <xs:documentation>Customization values defined in global scope.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence minOccurs = "0">
        <xs:element ref = "jaxb:javaType" minOccurs = "0" maxOccurs = "unbounded"/>
        <xs:element ref = "jaxb:serializable" minOccurs = "0"/>
        <xs:any namespace = "##other" processContents = "lax">
          <xs:annotation> 
            <xs:documentation>allows extension binding declarations to be specified.</xs:documentation>
          </xs:annotation>
        </xs:any>
      </xs:sequence>
      <xs:attributeGroup ref = "jaxb:XMLNameToJavaIdMappingDefaults"/>
      <xs:attributeGroup ref = "jaxb:typesafeEnumClassDefaults"/>
      <xs:attributeGroup ref = "jaxb:propertyAttributes"/>
      <xs:attribute name="generateValueClass" type="xs:boolean"
                    default= "true"/>
      <xs:attribute name="generateElementClass" type="xs:boolean"
                    default= "false"/>
      <xs:attribute name="mapSimpleTypeDef" type="xs:boolean"
                    default= "false"/>
      <xs:attribute name="localScoping" default= "nested">
        <xs:simpleType>
          <xs:restriction base="xs:NCName">
            <xs:enumeration value="nested"/>
            <xs:enumeration value="toplevel"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:attribute>
      <xs:attribute name = "enableJavaNamingConventions" default = "true" type = "xs:boolean"/>
      <xs:attribute name = "choiceContentProperty" default = "false" type = "xs:boolean"/>
    </xs:complexType>
  </xs:element>
  <xs:element name = "schemaBindings">
    <xs:annotation>
      <xs:documentation>Customization values with schema scope</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:all>
        <xs:element name = "package" type = "jaxb:packageType" minOccurs = "0"/>
        <xs:element name = "nameXmlTransform" type = "jaxb:nameXmlTransformType" minOccurs = "0"/>
      </xs:all>
    </xs:complexType>
  </xs:element>
  <xs:element name = "class">
    <xs:annotation>
      <xs:documentation>Customize interface and implementation class.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name = "javadoc" type = "xs:string" minOccurs = "0"/>
      </xs:sequence>
      <xs:attribute name = "name" type = "jaxb:javaIdentifierType">
        <xs:annotation>
          <xs:documentation>Java class name without package prefix.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name = "implClass" type = "jaxb:javaIdentifierType">
        <xs:annotation>
          <xs:documentation>Implementation class name including package prefix.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name="generateValueClass" type="xs:boolean">
        <xs:annotation>
          <xs:documentation>Default value derived from [jaxb:globalBindings]@generateValueClass.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name = "property">
    <xs:annotation>
      <xs:documentation>Customize property.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:all>
        <xs:element name = "javadoc" type = "xs:string" minOccurs="0"/>
        <xs:element name = "baseType" type="jaxb:propertyBaseType" minOccurs="0"/>
      </xs:all>
      <xs:attribute name = "name" type = "jaxb:javaIdentifierType"/>
      <xs:attributeGroup ref = "jaxb:propertyAttributes"/>
    </xs:complexType>
  </xs:element>
  <xs:element name = "javaType">
    <xs:annotation>
      <xs:documentation>Data type conversions; overriding builtins</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:attribute name = "name" use = "required" type = "jaxb:javaIdentifierType">
        <xs:annotation>
          <xs:documentation>name of the java type to which xml type is to be bound.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name = "xmlType" type = "xs:QName">
        <xs:annotation>
          <xs:documentation> xml type to which java datatype has to be bound.Must be present when javaType is scoped to globalBindings</xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name = "parseMethod" type = "jaxb:javaIdentifierType"/>
      <xs:attribute name = "printMethod" type = "jaxb:javaIdentifierType"/>
      <xs:attribute name = "hasNsContext" default = "false" type = "xs:boolean" >
        <xs:annotation>
          <xs:documentation>
            If true, the parsMethod and printMethod must reference a method
            signtature that has a second parameter of type NamespaceContext.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name = "typesafeEnumClass">
    <xs:annotation>
      <xs:documentation> Bind to a type safe enumeration class.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name = "javadoc" type = "xs:string" minOccurs = "0"/>
        <xs:element ref = "jaxb:typesafeEnumMember" minOccurs = "0" maxOccurs = "unbounded"/>
      </xs:sequence>
      <xs:attribute name = "name" type = "jaxb:javaIdentifierType"/>
      <xs:attribute name = "map" type = "xs:boolean" default = "true"/>
    </xs:complexType>
  </xs:element>
  <xs:element name = "typesafeEnumMember">
    <xs:annotation>
      <xs:documentation> Enumeration member name in a type safe enumeration class.</xs:documentation>
    </xs:annotation>
    <xs:complexType>
      <xs:sequence>
        <xs:element name = "javadoc" type = "xs:string" minOccurs = "0"/>
      </xs:sequence>
      <xs:attribute name = "value" type="xs:anySimpleType"/>
      <xs:attribute name = "name" use = "required" type = "jaxb:javaIdentifierType"/>
    </xs:complexType>
  </xs:element>

  <!-- TYPE DEFINITIONS -->

  <xs:complexType name = "propertyBaseType">
    <xs:all>
      <xs:element ref = "jaxb:javaType" minOccurs = "0"/>
    </xs:all>
    <xs:attribute name = "name" type = "jaxb:javaIdentifierType">
      <xs:annotation>
        <xs:documentation>
          The name attribute for [baseType] enables more precise control over the actual base type for a JAXB property. This customization enables specifying a more general base type than the property's default base type. The name attribute value must be a fully qualified Java class name. Additionally, this Java class must be a super interface/class of the default Java base type for the property. When the default base type is a primitive type, consider the default Java base type to be the Java wrapper class of that primitive type.This customization is useful to enable simple type substitution for a JAXB property representing with too restrictive of a default base type.
        </xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name = "packageType">
    <xs:sequence>
      <xs:element name = "javadoc" type = "xs:string" minOccurs = "0"/>
    </xs:sequence>
    <xs:attribute name = "name" type = "jaxb:javaIdentifierType"/>
  </xs:complexType>
  <xs:simpleType name = "underscoreBindingType">
    <xs:annotation>
      <xs:documentation>Treate underscore  in XML Name to Java identifier mapping.</xs:documentation>
    </xs:annotation>
    <xs:restriction base = "xs:string">
      <xs:enumeration value = "asWordSeparator"/>
      <xs:enumeration value = "asCharInWord"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name = "typesafeEnumBaseType">
    <xs:annotation>
      <xs:documentation>
        XML types or types derived from them which have enumeration facet(s)
        which are be mapped to typesafeEnumClass by default.
        The following types cannot be specified in this list:
         "xsd:QName", "xsd:base64Binary", "xsd:hexBinary",
         "xsd:date", "xsd:time", "xsd:dateTime", "xsd:duration",
         "xsd:gDay", "xsd:gMonth", "xsd:Year", "xsd:gMonthDay", "xsd:YearMonth"
      </xs:documentation>
    </xs:annotation>
    <xs:list itemType = "xs:QName"/>
  </xs:simpleType>
  <xs:simpleType name = "typesafeEnumMemberNameType">
    <xs:annotation>
      <xs:documentation>Used to customize how to handle name collisions.</xs:documentation>
    </xs:annotation>
    <xs:restriction base = "xs:string">
      <xs:enumeration value = "generateName"/>
      <xs:enumeration value = "generateError"/>
      <xs:enumeration value = "skipGeneration"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name = "javaIdentifierType">
    <xs:annotation>
      <xs:documentation>Placeholder type to indicate Legal Java identifier.</xs:documentation>
    </xs:annotation>
    <xs:list itemType = "xs:NCName"/>
  </xs:simpleType>
  <xs:complexType name = "nameXmlTransformRule">
    <xs:annotation>
      <xs:documentation>Rule to transform an Xml name into another Xml name</xs:documentation>
    </xs:annotation>
    <xs:attribute name = "prefix" type = "xs:string">
      <xs:annotation>
        <xs:documentation>prepend the string to QName.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
    <xs:attribute name = "suffix" type = "xs:string">
      <xs:annotation>
        <xs:documentation>Append the string to QName.</xs:documentation>
      </xs:annotation>
    </xs:attribute>
  </xs:complexType>
  <xs:complexType name = "nameXmlTransformType">
    <xs:annotation>
      <xs:documentation>Allows transforming an xml name into another xml name. Use case UDDI 2.0 schema.</xs:documentation>
    </xs:annotation>
    <xs:all>
      <xs:element name = "typeName" type = "jaxb:nameXmlTransformRule" minOccurs = "0">
        <xs:annotation>
          <xs:documentation>Mapping rule for type definitions.</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name = "elementName" type = "jaxb:nameXmlTransformRule" minOccurs = "0">
        <xs:annotation>
          <xs:documentation>Mapping rule for elements</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name = "modelGroupName" type = "jaxb:nameXmlTransformRule" minOccurs = "0">
        <xs:annotation>
          <xs:documentation>Mapping rule  for model group</xs:documentation>
        </xs:annotation>
      </xs:element>
      <xs:element name = "anonymousTypeName" type = "jaxb:nameXmlTransformRule" minOccurs = "0">
        <xs:annotation>
          <xs:documentation>Mapping rule for class names generated for an anonymous type.</xs:documentation>
        </xs:annotation>
      </xs:element>
    </xs:all>
  </xs:complexType>
  <xs:attribute name = "extensionBindingPrefixes">
    <xs:annotation>
      <xs:documentation>
        A binding compiler only processes this attribute when it occurs on an
        an instance of xs:schema element.  The value of this attribute is a
        whitespace-separated list of namespace prefixes.  The namespace bound
        to each of the prefixes is designated as a customization declaration
        namespace.
      </xs:documentation>
    </xs:annotation>
    <xs:simpleType>
      <xs:list itemType = "xs:normalizedString"/>
    </xs:simpleType>
  </xs:attribute>
  <xs:element name = "bindings">
    <xs:annotation>
      <xs:documentation>
        Binding declaration(s) for a remote schema.
        If attribute node is set, the binding declaraions
        are associated with part of the remote schema
        designated by schemaLocation attribute. The node
        attribute identifies the node in the remote schema
        to associate the binding declaration(s) with.
      </xs:documentation>
    </xs:annotation>
    <!-- a <bindings> element can contain arbitrary number of binding declarations or nested <bindings> elements -->
    <xs:complexType>
      <xs:sequence>
        <xs:choice minOccurs = "0" maxOccurs = "unbounded">
          <xs:group ref = "jaxb:declaration"/>
          <xs:element ref = "jaxb:bindings"/>
        </xs:choice>
      </xs:sequence>
      <xs:attribute name = "schemaLocation" type = "xs:anyURI">
        <xs:annotation>
          <xs:documentation>
            Location of the remote schema to associate binding declarations with.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name = "node" type = "xs:string">
        <xs:annotation>
          <xs:documentation>
            The value of the string is an XPATH 1.0 compliant string that
            resolves to a node in a remote schema to associate
            binding declarations with. The remote schema is specified
            by the schemaLocation attribute occuring in the current
            element or in a parent of this element.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute name = "version" type = "xs:token">
        <xs:annotation>
          <xs:documentation>
            Used to indicate the version of binding declarations. Only valid on root level bindings element.
            Either this or "jaxb:version" attribute but not both may be specified.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
      <xs:attribute ref = "jaxb:version">
        <xs:annotation>
          <xs:documentation>
            Used to indicate the version of binding declarations. Only valid on root level bindings element.
            Either this attribute or "version" attribute but not both may be specified.
          </xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="referenceCollectionType">
    <xs:union>
      <xs:simpleType>
        <xs:restriction base="xs:string">
          <xs:enumeration value="indexed"/>
        </xs:restriction>
      </xs:simpleType>
      <xs:simpleType>
        <xs:restriction base="jaxb:javaIdentifierType"/>
      </xs:simpleType>
    </xs:union>
  </xs:simpleType>
  <xs:element name="dom">
    <xs:complexType>
      <xs:attribute name = "type" type="xs:NCName" default="w3c">
        <xs:annotation>
          <xs:documentation>Specify DOM API to bind to JAXB property to.</xs:documentation>
        </xs:annotation>
      </xs:attribute>
    </xs:complexType>
  </xs:element>
  <xs:element name="inlineBinaryData">
    <xs:annotation>
      <xs:documentation>
        Disable MTOM/XOP encoding for this binary data. Annotation can be placed on a type definition that
        derives from a W3C XSD binary data type or on an element that has a type that is
        or derives from a W3C XSD binary data type.
      </xs:documentation>
    </xs:annotation>
  </xs:element>
  <xs:element name = "serializable">
    <xs:complexType>
      <xs:attribute name="uid" type="xs:long" default="1"/>
    </xs:complexType>
  </xs:element>
</xs:schema>
----