| 328 | | |
| 329 | | = Transformation of CCSL into a CMD profile schema = |
| 330 | | {{{#!div class="notice system-message" |
| 331 | | Responsible for this section: Twan |
| 332 | | }}} |
| 333 | | |
| 334 | | * A __CMD instance__ document that is serialised as XML according this specification '''SHOULD''' reference the location of a __CMD profile schema__. The infrastructure '''MUST''' provide a mechanism to derive such a schema for any specific __CMD profile__ on basis of its definition and that of the __CMD components__ that it references. This section specifies how different aspects of a __CMD specification__ should be transformed into elements of a schema definition. The primary schema language targeted is ''XML Schema'', although the infrastructure '''MAY''' provide support for other schema languages, such as ''DDML'' or ''Relax NG''. |
| 335 | | * __CMD profile schemas__ '''SHOULD NOT''' (MUST NOT?) be derived from __CMD specifications__ that are not __CMD profiles__. |
| 336 | | * The transformation as described here is assumed to take place on the fully ''expanded'' __CMD profile__, i.e. a version of the specification that has all referenced (non-inline) __CMD Component__ definitions are resolved and substituted, recursively, by their full definitions. |
| 337 | | |
| 338 | | * Global schema properties |
| 339 | | * A __CMD profile schema__ '''MUST''' be a single document [or set of linked documents with a single entry point](?) that allows for the evaluation of __CMD instance__ on all levels of description defined in one specific __CMD profile__. |
| 340 | | * The __CMD profile schema__ '''MUST''' use the following namespaces: |
| 341 | | * {cmd} http://www.clarin.eu/cmd/ |
| 342 | | * targeted namespace |
| 343 | | * {ann} [http://www.clarin.eu/ http://www.clarin.eu] |
| 344 | | * for annotation and documentation purposes that are outside the scope of instance validation |
| 345 | | * {dcr} http://www.isocat.org/ns/dcr |
| 346 | | * for embedded semantic annotation |
| 347 | | * {cue} http://www.clarin.eu/cmdi/cues/display/1.0 |
| 348 | | * for display cues |
| 349 | | * The __CMD profile schema__ '''MAY''' include, as a matter of annotation, a copy of (a subset of) the information contained in the ''Header'' section of the __CMD profile__ from which it is defined. |
| 350 | | * The __CMD profile schema__ '''MUST''' require the presence of a __CMD instance envelope__ as described in section [CMDI Instance/The main structure]. The value of the '!MdProfile' header item '''MUST''' only be valid if it is equal to the profile id as specified in the associated __CMD profile__. |
| 351 | | * ☐Transformation '''MAY''' make use of component ids to derive (complex) types that can be reused in the schema definition. |
| 352 | | |
| 353 | | * Interpretation of CMD component definitions in the CCSL |
| 354 | | * __CMD Components__, represented as "Component" __XML elements__ in the CCSL, '''MUST''' be realised as __XML element declarations__ with the following property mapping: |
| 355 | | * '''MANDATORY''': Name of the __XML element__: @name |
| 356 | | * '''MANDATORY''': Minimal number of occurrences: @!CardinalityMin, '''MUST''' be evaluated as '1' if this XML attribute is missing |
| 357 | | * '''MANDATORY''': Maximal number of occurrences: @!CardinalityMax unless @Multilingual is true, in which case '''MUST''' be 'unbounded', otherwise '''MUST''' be evaluated as '1' if @!CardinalityMax is not present |
| 358 | | * '''OPTIONAL''': Concept link by means of an __XML attribute__ "!dcr:datcat" on the __XML element__ within the schema definition: @!ConceptLink |
| 359 | | * '''OPTIONAL''': Component id by means of an __XML attribute__ "!cmd:ComponentId" on the __XML element__ within the schema definition: @!ComponentId |
| 360 | | * The first __CMD component__ defined in the __CMD profile__ (the 'root component') '''MUST''' be mapped as the mandatory, only direct descendant of the "Components" XML element of the CMD instance envelope. |
| 361 | | * __CMD components__ that are defined as direct descendants of another __CMD component__ '''MUST''' be mapped as direct descendants of the __XML element declaration__ to which it is transformed and '''MUST''' be required to be included in the same order as defined in the __CMD specification__, the first of the resulting __XML elements__ appearing after the last __XML element__'' ''derived from a __CMD element__ at the same level, if present. These __CMD Components__ '''MUST''' be mapped to __XML element declarations__ recursively as described in this specification. |
| 362 | | * An optional __XML Attribute__ "!cmd:ref" of type "!xs:IDREFS" '''MUST''' be allowed on the __XML container element__ derived from any __CMD component__. |
| 363 | | * "Documentation" __XML elements__ contained in __CMD Components__ '''MAY''' be transformed into documentation __XML elements__ embedded in the __XML element declaration__, in which case the content language information contained in the "!xml:lang" __XML attribute__ '''SHOULD''' be preserved. |
| 364 | | * ☐display cues (all attributes in cue namespace should be copied) |
| 365 | | |
| 366 | | * Interpretation of CMD element definitions in the CCSL |
| 367 | | * __CMD elements__, represented as "Element" __XML elements__ in the CCSL, '''MUST''' be realised as __XML element declarations__ with the following property mapping: |
| 368 | | * '''MANDATORY''': Name of the __XML element__: @name |
| 369 | | * '''MANDATORY''': Minimal number of occurrences: @!CardinalityMin, '''MUST''' be evaluated as '1' if this XML attribute is missing |
| 370 | | * '''MANDATORY''': Maximal number of occurrences: @!CardinalityMax unless @Multilingual is true, in which case '''MUST''' be 'unbounded', otherwise '''MUST''' be evaluated as '1' if @!CardinalityMax is not present |
| 371 | | * '''OPTIONAL''': Concept link by means of an __XML attribute__ "!dcr:datcat" on the __XML element__ within the schema definition: @!ConceptLink |
| 372 | | * ☐!AutoValue |
| 373 | | * __CMD elements__ '''MUST''' be mapped as direct descendants of the __XML element declaration__ derived from the __CMD component__ of which they are direct descendants, and '''MUST''' be required to be included in the same order as defined in the __CMD specification__. |
| 374 | | * The derivation of a content model for the __XML element__ __declaration__ on basis of a __CMD element__ is described below. |
| 375 | | * "Documentation" __XML elements__ contained in __CMD elements__ '''MAY''' be transformed into documentation __XML elements__ embedded in the __XML element declaration__, in which case the content language information contained in the "!xml:lang" __XML attribute__ '''SHOULD''' be preserved. |
| 376 | | * ☐display cues (all attributes in cue namespace should be copied) |
| 377 | | |
| 378 | | * Interpretation of CMD attribute definitions in the CCSL |
| 379 | | * __CMD attributes__, represented as "Attribute" __XML elements__ in the CCSL, '''MUST''' be realised as __XML attribute declarations__ with the following property mapping: |
| 380 | | * '''MANDATORY''': Name of the __XML attribute__: @name |
| 381 | | * '''MANDATORY''': Use of the __XML attribute__: '''MUST''' be required if and only if @Required is present and equals true, otherwise '''MUST''' evaluate to optional |
| 382 | | * '''OPTIONAL''': Concept link by means of an __XML attribute__ "!dcr:datcat" on the __XML element__ within the schema definition: @!ConceptLink |
| 383 | | * ☐!AutoValue |
| 384 | | * __CMD attributes__ that are defined in the CCSL within "Attribute" __XML elements__ within an "!AttributeList" __XML element__ that is a direct descendant of a __CMD Component__ '''MUST''' be mapped to __XML attribute__ definitions on the __XML container element__ to which it is transformed. |
| 385 | | * The derivation of a content model for the __XML attribute declaration__ on basis of a __CMD attribute__ is described below. |
| 386 | | * "Documentation" __XML elements__ contained in __CMD attributes__ '''MAY''' be transformed into documentation __XML elements__ embedded in the __XML attribute declaration__, in which case the content language information contained in the "!xml:lang" __XML attribute__ '''SHOULD''' be preserved. |
| 387 | | * ☐display cues (all attributes in cue namespace should be copied) |
| 388 | | |
| 389 | | * Content model |
| 390 | | * If a __CMD element__ or __CMD attribute__ in the CCSL has a "!ValueScheme" __XML attribute__, its value '''MUST''' be interpreted as the name of the __XML Schema Datatype__ that defines the allowed value range of the __XML element__ derived from the __CMD element__ or __XML attribute__ derived from the __CMD attribute__. |
| 391 | | * If a __CMD element__ or __CMD attribute__ in the CCSL has a descendant __XML element__ "!ValueScheme" that contains an __XML element__ "pattern", then its text value '''MUST''' be interpreted as the __XML Schema Regular Expressions__ that defines the allowed value range of the __XML element__ derived from this __CMD element__ or __XML attribute__ derived from the __CMD attribute__. |
| 392 | | * If a __CMD element__ or __CMD attribute__ in the CCSL has a descendant __XML element__ "!ValueScheme" that contains an __XML element__ "Vocabulary": |
| 393 | | * The __XML attributes__ "!ValueProperty" and "!ValueLanguage" of the __XML element__ "Vocabulary" '''MAY''' be transformed into XML attributes in the "ann" namespace on the __XML element declaration__ in the case of a __CMD element__ or __XML attribute declaration__ in the case of a __CMD attribute__. |
| 394 | | * The __XML attribute__ "URI" of the __XML element__ "Vocabulary", if present, '''MUST''' be transformed into an attribute "!cmd:ValueConceptLink" of the same value on the __XML element declaration__ in the case of a __CMD element__ or __XML attribute declaration__ in the case of a __CMD attribute__. |
| 395 | | * The __XML elements__ "item" that are descendants of the __XML element__ "enumeration" contained in the __XML element__ "Vocabulary" '''MUST''' be transformed into an enumeration based restriction with values taken from the text content of the "item" __XML elements__. Each enumeration item in the schema '''MAY''' be annotated the value from the __XML attribute__ "!ConceptLink" by means of an __XML attribute__ "!dcr:datcat" and the value of the __XML attribute__ "!AppInfo" by means of an attribute in the "ann" namespace. |
| | 328 | = Transformation of CCSL into a CMD profile schema definition = |
| | 329 | |
| | 330 | A CMD instance document that is serialised as XML according this specification `SHOULD` contain a reference the location of a CMD profile schema. The infrastructure `MUST` provide a mechanism to derive such a schema for any specific CMD profile on basis of its definition and that of the CMD components that it references. This section specifies how different aspects of a CMD specification should be transformed into elements of a schema definition. The primary schema language targeted is XML Schema, although the infrastructure `MAY` provide support for other schema languages, such as DDML or Relax NG. |
| | 331 | CMD profile schemas `SHOULD NOT` (`MUST NOT`?) be derived from CMD specifications that are not CMD profiles. |
| | 332 | |
| | 333 | The transformation as described here is assumed to take place on the fully expanded CMD profile, i.e. a version of the specification that has all referenced (non-inline) CMD Component definitions are resolved and substituted, recursively, by their full definitions. |
| | 334 | |
| | 335 | == General properties of the CMD profile schema definition == |
| | 336 | |
| | 337 | A CMD profile schema `MUST` be a single document {or set of linked documents with a single entry point}(?) that allows for the evaluation of a CMD instance on all levels of description defined in one specific CMD profile. |
| | 338 | The schema `MUST` require the presence of a CMD instance envelope as described in section "Structure of CMDI-files". The value of the `<MdProfile>` header item in the CMD instance envelope `MUST` only be valid if it is equal to the profile id as specified in the associated CMD profile. |
| | 339 | |
| | 340 | The CMD profile schema `SHOULD` include, as a matter of annotation, a copy of (a subset of) the information contained in the `Header` section of the CMD profile from which it is derived. |
| | 341 | |
| | 342 | The transformation `MAY` make use of embedded component identifiers in the CMD component definition to derive (complex) types that can be reused throughout the schema definition. |
| | 343 | |
| | 344 | == Interpretation of CMD component definitions in the CCSL == |
| | 345 | CMD Components which are represented as `<Component>` XML elements in the CCSL, `MUST` be realised as XML element declarations with the following property mapping: |
| | 346 | |
| | 347 | ||= Property =||= XML schema attribute =||= Derived from =||= Use =|| |
| | 348 | || Name of the XML element || `@name` || `@name` || `REQUIRED` || |
| | 349 | || Minimal number of occurrences || `@minOccurs` || `@CardinalityMin`, or '1' if XML attribute not present || `REQUIRED` ^[#ioccditc-note1 1]^ || |
| | 350 | || Maximal number of occurrences || `@maxOccurs` || `@CardinalityMax`, or '1' if XML attribute not present || `REQUIRED` ^[#ioccditc-note1 1]^ || |
| | 351 | || Concept link || `@dcr:datcat` || `@ConceptLink` || `OPTIONAL` || |
| | 352 | || Component id || `@cmd:ComponentId` || `@ComponentId` || `OPTIONAL` || |
| | 353 | ^[=#ioccditc-note1 1]^The implementation may make use of default evaluation of the schema language if it matches these requirements, as is the case with XML Schema, and therefore omit explicit declaration of these properties |
| | 354 | |
| | 355 | An optional XML Attribute `@cmd:ref` of type ''xs:IDREFS'' `MUST` be allowed on the XML container element derived from any CMD component. |
| | 356 | |
| | 357 | `<Documentation>` XML elements contained in CMD Components `SHOULD` be transformed into documentation elements embedded in the XML element declaration. In these, the content language information contained in the `@xml:lang` XML attribute `SHOULD` be preserved. |
| | 358 | |
| | 359 | XML attributes of CMD Components in the 'cue' namespace `SHOULD` be copied into the XML element declaration, in which case the XML attribute name, namespace and value `SHOULD` be preserved. |
| | 360 | |
| | 361 | === Document structure prescribed by the schema === |
| | 362 | |
| | 363 | The first CMD component defined in the CMD profile (the "root component") `MUST` be mapped as the mandatory, only direct descendant of the `<Components>` XML element of the CMD instance envelope. |
| | 364 | CMD components that are defined as direct descendants of another CMD component `MUST` be mapped as direct descendants of the XML element declaration to which it is transformed. XML components at the CMD component level in the metadata instance `MUST` be required to be included in the same order as defined in the CMD specification, the first of the resulting XML elements appearing after the last XML element derived from a CMD element at the same level, if present. These descendant CMD Components `MUST` also be mapped to XML element declarations recursively as described in this specification. |
| | 365 | |
| | 366 | CMD elements `MUST` be mapped as direct descendants of the XML element declaration derived from the CMD component of which they are direct descendants, and `MUST` be required to be included in the same order as defined in the CMD specification. |
| | 367 | |
| | 368 | CMD attributes that are defined in the CCSL within "Attribute" XML elements within an "AttributeList" XML element that is a direct descendant of a CMD Component MUST be mapped to XML attribute definitions on the XML container element to which it is transformed. |
| | 369 | |
| | 370 | == Interpretation of CMD element definitions in the CCSL == |
| | 371 | CMD elements, represented as `<Element>` XML elements in the CCSL, `MUST` be realised as XML element declarations with the following property mapping: |
| | 372 | |
| | 373 | ||= Property =||= XML schema attribute =||= Derived from =||= Use =|| |
| | 374 | || Name of the XML element || `@name` || `@name` || `REQUIRED` || |
| | 375 | || Minimal number of occurrences || `@minOccurs` || `@CardinalityMin` '''unless''' `@Multilingual` is true,\\in which case MUST be 'unbounded',\\or '1' if neither XML attribute is present || `REQUIRED` ^[#ioceditc-note1 1]^ || |
| | 376 | || Maximal number of occurrences || `@maxOccurs` || `@CardinalityMax`, or '1' if XML attribute not present || `REQUIRED` ^[#ioceditc-note1 1]^ || |
| | 377 | || Type of the XML element || `@type` || See section 'Content model' || || |
| | 378 | || Concept link || `@dcr:datcat` || `@ConceptLink` || `OPTIONAL` || |
| | 379 | || Auto value instruction || `@cmd:AutoValue` || `@AutoValue` || `OPTIONAL` || |
| | 380 | ^[=#ioceditc-note1 1]^The implementation may make use of default evaluation of the schema language if it matches these requirements, as is the case with XML Schema, and therefore omit explicit declaration of these properties |
| | 381 | |
| | 382 | `<Documentation>` XML elements contained in CMD elements `SHOULD` be transformed into documentation elements embedded in the XML element declaration In these, the content language information contained in the `@xml:lang` XML attribute `SHOULD` be preserved. |
| | 383 | |
| | 384 | XML attributes of CMD Elements in the 'cue' namespace `SHOULD` be copied into the XML element declaration, in which case the XML attribute name, namespace and value `SHOULD` be preserved. |
| | 385 | |
| | 386 | An optional XML Attribute `@cmd:ValueConceptLink` of type ''xs:anyURI'' `MUST` be allowed on the XML element derived from a CMD element that has a vocabulary with XML attribute `@URI` defined (see section "Content model for CMD elements and CMD attributes in the schema definition"). |
| | 387 | |
| | 388 | The derivation of a content model for the XML element declaration on basis of a CMD element is described below. |
| | 389 | |
| | 390 | == Interpretation of CMD attribute definitions in the CCSL == |
| | 391 | CMD attributes, represented as `<Attribute>` XML elements in the CCSL, `MUST` be realised as XML attribute declarations with the following property mapping: |
| | 392 | |
| | 393 | ||= Property =||= XML schema attribute =||= Derived from =||= Use =|| |
| | 394 | || Name of the XML element || `@name` || `@name` || `REQUIRED` || |
| | 395 | || Use of the XML attribute || `@use` || 'required' if and only if `@Required` is present and equals true, otherwise 'optional' || `REQUIRED` ^[#iocaditc-note1 1]^ || |
| | 396 | || Type of the XML attribute || `@type` |||| See section 'Content model' || |
| | 397 | || Concept link || `@dcr:datcat` || `@ConceptLink` || `OPTIONAL` || |
| | 398 | || Auto value instruction || `@cmd:AutoValue` || `@AutoValue` || `OPTIONAL` || |
| | 399 | ^[=#iocaditc-note1 1]^The implementation may make use of default evaluation of the schema language if it matches these requirements, as is the case with XML Schema, and therefore omit explicit declaration of these properties |
| | 400 | |
| | 401 | `<Documentation>` XML elements contained in CMD attributes `SHOULD` be transformed into documentation elements embedded in the XML attribute declaration In these, the content language information contained in the `@xml:lang` XML attribute `SHOULD` be preserved. |
| | 402 | |
| | 403 | XML attributes of CMD Attributes in the 'cue' namespace `SHOULD` be copied into the XML attribute declaration, in which case the XML attribute name, namespace and value `SHOULD` be preserved. |
| | 404 | |
| | 405 | The derivation of a content model for the XML attribute declaration on basis of a CMD attribute is described below. |
| | 406 | |
| | 407 | == Content model for CMD elements and CMD attributes in the schema definition == |
| | 408 | If a CMD element or CMD attribute in the CCSL has a `@ValueScheme` XML attribute, its value `MUST` be interpreted as the name of the XML Schema Datatype (declared in the `@type` attribute of the XML element or attribute declaration in XML Schema) that defines the allowed value range of the XML element/attribute derived from the CMD element/attribute. |
| | 409 | |
| | 410 | '''Otherwise''', if a CMD element or CMD attribute in the CCSL has a descendant XML element `<ValueScheme>` that contains an XML element `<pattern>`, then its text value `MUST` be interpreted as the XML Schema Regular Expressions that defines the allowed value range of the XML element/attribute derived from this CMD element/attribute. |
| | 411 | |
| | 412 | '''Otherwise''', if a CMD element or CMD attribute in the CCSL has a descendant XML element `<ValueScheme>` that contains an XML element `<Vocabulary>`: |
| | 413 | * The XML attribute `@URI` of the XML element `<Vocabulary>`, if present, `SHOULD` be transformed into an attribute `cmd:Vocabulary`^[#cm-note1 1]^ of the same value on the XML element or attribute declaration in the schema. |
| | 414 | * The XML attributes `@ValueProperty` and `@ValueLanguage` of the XML element `<Vocabulary>` `SHOULD` be transformed into XML attributes^[#cm-note1 1]^ in the 'cmd:' namespace on the XML element declaration in the case of a CMD element or XML attribute declaration in the case of a CMD attribute. |
| | 415 | * The XML elements `<item>` that are descendants of `<enumeration>` contained in `<Vocabulary>` `MUST` be transformed into an enumeration based restriction with values taken from the text content of the `<item>` XML elements. Each enumeration item in the schema `SHOULD` be annotated the value from the XML attribute `@ConceptLink` by means of an XML attribute `@dcr:datcat`^[#cm-note1 1]^ and the value of the XML attribute `@AppInfo` by means of an attribute in the 'ann' namespace. |
| | 416 | |
| | 417 | ^[=#cm-note1 1]^The attributes `@cmd:Vocabulary`, `@cmd:ValueProperty`, `@cmd:ValueLanguage` and `@dcr:datcat` should be present in the schema, not be declared as attributes allowed in the CMD instance |
