YASD, Yet Another Schema Definition

YASD is a YAML format for human writable XSDs (XML Schema Definition), humans declare what is indispensable, leaving the machines to do the rest of the unreadable <syntaxis who_can_read_this="?" />.

CLI Workflow

The following chart is the YASD CLI workflow:

flowchart LR
    direction LR
    yasd --- convert
    yasd --- check
    yasd --- sample
    yasd --- document
    yasd --- man
    convert --- |from| YASD1([YASD])
    YASD1 --> |to| XSD([XSD])
    check --- |validates| YASD2([YASD])
    sample --- |from| YASD3([YASD])
    YASD3 --> |to| XML([XML])
    document --- |from| YASD4([YASD])
    YASD4 --> |to| RST([reStructuredText])
    man --- |prints| README

Example

To better understad what YASD does, see the inputs and outputs:

• Input: human workable schema in YASD.
• Output: computer processable schema in XSD.
• Output: human readable documentation in reStructuredText.

Table of Contents

TOC

Structure

General Structure

schema:
  SCHM 
elements:
  - ELMT
  ...
attributeElements:
  - ATTR
  ...
groups:
  - GRPS

Schema (SCHM) Structure

elementFormDefault: qualified|unqualified
targetNamespace: http://a.link
xmlns: http://a.link
schemaLocation: http://a-link-to.xsd
version: 0.1

Element (ELMT) Structure

name: element_name
description: Element description
type: simple|empty|no_text|no_elements|mixed 
datatype: string|integer|decimal|date|time|language|duration|token|boolean|byte|int|double|float|long|short|normalizedString|dateTime|gDay|gMonth|gMonthDay|gYear|gYearMonth|negativeInteger|nonNegativeInteger|nonPositiveInteger|positiveInteger|unsignedLong|unsignedInt|unsignedShort|unsignedByte|anyURI|base64Binary|hexBinary|Name|QName|NCName|ID|IDREF|IDREFS|ENTITY|ENTITIES|NMTOKEN|NMTOKENS|NOTATION
attributes:
  - ref: attribute_name
    use: optional|required|prohibited
  - group: group_name
  ...
children_order: all|choice|sequence
children:
  - ref: element_name
    maxOccurs: INTEGER|unbounded
    minOccurs: INTEGER
  - group: group_name
    maxOccurs: INTEGER|unbounded
    minOccurs: INTEGER
    remove:
      - element_or_attribute_name
  ...

Attribute (ATTR) Structure

name: attribute_name
description: Attribute description
datatype: string|integer|decimal|date|time|language|duration|token|boolean|byte|int|double|float|long|short|normalizedString|dateTime|gDay|gMonth|gMonthDay|gYear|gYearMonth|negativeInteger|nonNegativeInteger|nonPositiveInteger|positiveInteger|unsignedLong|unsignedInt|unsignedShort|unsignedByte|anyURI|base64Binary|hexBinary|Name|QName|NCName|ID|IDREF|IDREFS|ENTITY|ENTITIES|NMTOKEN|NMTOKENS|NOTATION
default: a_value
fixed: a_value
restriction:
  - CONSTRAIN
  ...

Group (GRPS) Structure

name: group_name
attribute_group: true|false
children_order: all|choice|sequence 
children:
  - ref: element_or_attribute_name
    maxOccurs: INTEGER|unbounded
    minOccurs: INTEGER

Key Reference

attribute_group

Indicates if group is an attribute group.

Optional; if not present by default is false.

Allowed values:

• true.
• false.

attributeElements

Indicates attributes elements for schema.

Optional.

attributes

Indicates a list of attributes for an element.

children_order

Indicates order indicators for children elements.

Mandatory in no_text or mixed elements, and group.

Allowed values:

• all. Children elements can occur in any order.
• choice. Only one children element can accur.
• sequence. Children elements must occur in specified order.

children

Indicates a list of children elements.

Mandatory in no_text or mixed elements, and group.

datatype

Indicates element or attribute data types.

Only mandatory for 'simple' and 'no_elements' elements, and attributes.

Allowed String Data Types:

• ENTITIES.  
• ENTITY.  
• ID. A string that represents the ID attribute in XML (only used with schema attributes).
• IDREF. A string that represents the IDREF attribute in XML (only used with schema attributes).
• IDREFS.
• language. A string that contains a valid language id.
• Name. A string that contains a valid XML name.
• NCName.
• NMTOKEN. A string that represents the NMTOKEN attribute in XML (only used with schema attributes).
• NMTOKENS.
• normalizedString. A string that does not contain line feeds, carriage returns, or tabs.
• QName.
• string. A string.
• token. A string that does not contain line feeds, carriage returns, tabs, leading or trailing spaces, or multiple spaces.

Allowed Date and Time Data Types:

• date. Defines a date value.
• dateTime. Defines a date and time value.
• duration. Defines a time interval.
• gDay. Defines a part of a date - the day (DD).
• gMonth. Defines a part of a date - the month (MM).
• gMonthDay. Defines a part of a date - the month and day (MM-DD).
• gYear. Defines a part of a date - the year (YYYY).
• gYearMonth. Defines a part of a date - the year and month (YYYY-MM).
• time. Defines a time value.

Allowed Numeric Data Types:

• byte. A signed 8-bit integer.
• decimal. A decimal value.
• int. A signed 32-bit integer.
• integer. An integer value.
• long. A signed 64-bit integer.
• negativeInteger. An integer containing only negative values (..,-2,-1).
• nonNegativeInteger. An integer containing only non-negative values (0,1,2,..).
• nonPositiveInteger. An integer containing only non-positive values (..,-2,-1,0).
• positiveInteger. An integer containing only positive values (1,2,..).
• short. A signed 16-bit integer.
• unsignedLong. An unsigned 64-bit integer.
• unsignedInt. An unsigned 32-bit integer.
• unsignedShort. An unsigned 16-bit integer.
• unsignedByte. An unsigned 8-bit integer.

Allowed Miscellaneous Data Types:

• anyURI.
• base64Binary.
• boolean.
• double.
• float.
• hexBinary.
• NOTATION.
• QName.

default

Indicates default value when element or attribute is empty.

Optional.

Only allowed for simple elements or attributes.

description

Indicates element or attribute description in human readable form.

Optional.

elementFormDefault

Indicates that any elements used by the XML instance document which were declared in this schema must be namespace qualified.

Optional; if not present by default is unqualified.

elements

Indicates elements for schema.

Mandatory.

fixed

Indicates fixed value to element or attribute.

Optional; ignored if 'default' is present.

Only allowed for simple elements or attributes.

group

References group name.

Optional.

groups

Indicates element or attribute groups for schema.

Optional.

maxOccurs

Indicates max number of times a children element can accur.

Optional; if not present by default is 1.

Valid values are non negative integer or unbounded for unlimited number of times.

minOccurs

Indicates min number of times a children element can accur.

Optional; if not present by default is 1.

Valid value is non negative integer.

name

Indicates element, attribute or group name.

Mandatory.

For elements, its name is commonly known as tag name.

Naming rules:

• Element names are case-sensitive
• Element names must start with a letter or underscore
• Element names cannot start with the letters xml (or XML, or Xml, etc)
• Element names can contain letters, digits and underscores
• Element names cannot contain spaces or hyphens

ref

References element or attribute by name.

Mandatory.

remove

Removes element or attribute from group by name.

Optional.

restriction

Indicates accepted constrained values for attribute.

Optional; if present, must contain at least one constrain and attribute datatype is ignored.

Allowed constrains:

• enumeration. Specifies a list of acceptable values.
• fractionDigits. Specifies the maximum number of decimal places allowed; must be equal to or greater than zero.
• length. Specifies the exact number of characters or list items allowed; must be equal to or greater than zero.
• maxExclusive. Specifies the upper bounds for numeric values (the value must be less than this value).
• maxInclusive. Specifies the upper bounds for numeric values (the value must be less than or equal to this value).
• maxLength. Specifies the maximum number of characters or list items allowed; must be equal to or greater than zero.
• minExclusive. Specifies the lower bounds for numeric values (the value must be greater than this value).
• minInclusive. Specifies the lower bounds for numeric values (the value must be greater than or equal to this value).
• minLength. Specifies the minimum number of characters or list items allowed; must be equal to or greater than zero.
• pattern. Defines the exact sequence of characters that are acceptable.
• totalDigits. Specifies the exact number of digits allowed; must be greater than zero.
• whiteSpace. Specifies how white space (line feeds, tabs, spaces, and carriage returns) is handled; accepted values are preserve|replace|collapse.

schema

Indicates schema general information.

Mandatory.

schemaLocation

Indicates the location of the XML schema to use for that namespace.

Optional.

taget_namespace

Indicates that the elements defined by this schema come from the specified URL namespace.

Optional.

type

Indicates element type.

Mandatory.

Allowed types:

• simple. Only text node allowed.
• empty. Only attributes allowed.
• no_text. No children text nodes allowed.
• no_elements. No children elements allowed.
• mixed. Children elements, text node and attributes allowed.

Chart:

| type        | elements | text | attributes |
|-------------|:--------:|:----:|:----------:|
| simple      | ✗        | ✓    | ✗          |
| empty       | ✗        | ✗    | ✓          |
| no_text     | ✓        | ✗    | ✓          |
| no_elements | ✗        | ✓    | ✓          |
| mixed       | ✓        | ✓    | ✓          |

Note 1: read "elements" and "text" with "direct children..." as prefix.

Note 2: attributes are never mandatory; they could be zero or more.

use

Indicates that the attribute is required.

Optional; if not present by default is optional.

Allowed uses:

• optional.
• required.
• prohibited.

version

Indicates XML schema version.

Mandatory.

xmlns

Indicates that the default namespace is the specified URL.

Mandatory.

References

• "XML Schema Reference", W3ref
• "XML Schema Tutorial", W3Schools.
• "XSD Tutorial", Tutorials Point.

License

YASD is under GPLv3, check the license terms here.

Acknowledgments

YASD is founded by Mexican Academy of Language.

License

YASD is under GPLv3, check the license terms [here]