schema contribution guidelines

[lzehl]

• Order of first level schema items: _extends (if applicable), _type (if applicable), _categories (if applicable), required, properties
• All properties of a schema should be alphabetically ordered.
• Specify all properties (with null where not yet defined).
• Default language setting is US English.
• Instances are written in JSON-LD compact 1 format.
• Use 2 spaces per nested level (not tabs) as indentation.
• New Line placed after commas , as well as opening, non-empty braces { and brackets [.
• Includes 1 space after in-line colons : and commas ,.
• Include new line after the last closing brace }.
• A schema should specify a set of properties that meaningfully represents a type of entity or activity.
• Avoid one-to-many connections, unless justified.
• A schema should not directly specify nested schema definitions (cf. linked and embedded schemas).
• A schema should be linked, not embedded, if the respective entity or activity can stand on its own.
• A schema should be embedded, not linked, if the respective entity or activity exists only in context of a "parent" entity or activity and does not need to be linked to by any other entity (e.g. time varying entities).
  • Exception:
    • sensitive information: If properties containing personal data should be defined in a separate schema to allow fine grained access control.
• A time-varying entity should be represented in two interlinked schemas, one for the time-independent and one for the time-dependent information.
  • link logic:
    • old: time-independent links to 1-N time-dependent schemas
    • new: time-dependent schema links to 1 time-independent schema
• Only properties that can be always be expected should be made required.
• Schema properties should be consistently reduced to a minimum, meaning the reuse of a property name across schemas is highly recommended, if the definition of that property name remains the same.