mdf-schema.yaml

$schema: http://json-schema.org/draft-06/schema#
$id: https://github.com/CBIIT/bento-mdf/schema/mdf-schema.yaml#

type: object
properties:
  Nodes:
    propertyNames:
      $ref: "#/defs/snake_case_id"
    additionalProperties:
      $ref: "#/defs/nodeSpec"
  Relationships:
    propertyNames:
      $ref: "#/defs/snake_case_id"
    additionalProperties:
      $ref: "#/defs/relnSpec"
  PropDefinitions:
    propertyNames:
      $ref: "#/defs/snake_case_id"
    additionalProperties:
      $ref: "#/defs/propSpec"
  Terms:
    propertyNames:
      # $ref: "#/defs/snake_case_id"
      type: string
    additionalProperties:
      $ref: "#/defs/termSpec"
  UniversalNodeProperties:
    type: object
    properties:
      mustHave:
        desc: |
          items are names of properties that every node *must* have;
          properties are defined in PropDefinitions
        type: array
        items:
          $ref: "#/defs/snake_case_id"
      mayHave:
        desc: |
          items are names of properties that every node *may* have;
          properties are defined in PropDefinitions
        type: array
        items:
          $ref: "#/defs/snake_case_id"
  UniversalRelationshipProperties:
    type: object
    properties:
      mustHave:
        desc: |
          items are names of properties that every relationship *must* have;
          properties are defined in PropDefinitions      
        type: array
        items:
          $ref: "#/defs/snake_case_id"
      mayHave:
        desc: |
          items are names of properties that every relationship *may* have;
          properties are defined in PropDefinitions      
        type: array
        items:
          $ref: "#/defs/snake_case_id"
  Tags:
    $ref: "#/defs/tagsSpec"
  Handle:
    type: string
    desc: |
      This is a human-readable short name for the model described in the MDF, that
      should also be understood as a token that can be used to extract the model
      from a Metamodel Database
  Version:
    type: string
    desc: |
      This is a human-readable version string (e.g., v1.7.2) for the model described
      in the MDF. Best practice is to keep it in sync with a git tag for which a
      GitHub release has been made.
  URI:
    $ref: "#/defs/url"
    desc: |
      If present, this should be a resolving URL that can provide further detailed information
      about the model described in the MDF instance. Ideally, it should be the base URL for a
      terminology server (like the Simple Terminology Server), that can be concatenated with
      path information in the MDF to return details. Currently, an enumerated value set can
      be included "by reference" in the MDF, using a path. Joining the URL value and the
      path value with a backslash should create a url that resolves to a REST GET access of
      an STS that can return the actual list of enumerated values.
    
      
    
required:
  - Nodes
  - Relationships

propertyNames:
  $ref: "#/defs/camelCaseId"

additionalProperties: true

defs:
  snake_case_id:
    $id: "#snake_case_id"
    type: string
    pattern: "^[A-Za-z_0-9][A-Za-z0-9_.]*$"
  camelCaseId:
    $id: "#camelCaseId"
    type: string
    pattern: "^[A-Z][A-Za-z]*$"
  fileNameId:
    $id: "#fileNameId"
    type: string
    pattern: "^[A-Za-z0-9_-~/.]+\\.json|jsn|yml|yaml$"
  nanoid:
    $id: "#nanoid"
    type: string
    pattern: "^[abcdefghijkmnopqrstuvwxyzABCDEFGHJKMNPQRSTUVWXYZ0123456789]{6}$"
  url:
    $id: "#url"
    type: string
    pattern: ((([A-Za-z]{3,9}:(?:\/\/)?)(?:[\-;:&=\+\$,\w]+@)?[A-Za-z0-9\.\-]+|(?:www\.|[\-;:&=\+\$,\w]+@)[A-Za-z0-9\.\-]+)((?:\/[\+~%\/\.\w\-_]*)?\??(?:[\-\+=&;%@\.\w_]*)#?(?:[\.\!\/\\\w]*))?)
  path:
    $id: "#path"
    type: string
    description: |
      The \'path\' is intended to describe a string that can be appended to the
      base url of a terminology service endpoint. The expected response from
      the server is a simple array of acceptable values as strings (possibly
      embedded somewhere in a response structure).
      A path must start with a forward slash. If the base url ends with a forward slash,
      the concatenation should replace two consecutive forward slashes with one.
    pattern: /^[/][A-Za-z0-9_][A-Za-z0-9._-~]*(?:[/&?][A-Za-z0-9_][A-Za-z0-9._-~=%]*)*/
  regex:
    $id: "#regex"
    type: object
    properties:
      pattern:
        type: string
      flavor:
        description: |
          Can tag as JS, Perl, egrep, whatever, here (optional)
        type: string
    required:
      - pattern
  simpleType:
    description: |
      simpleType (a scalar)
    type: string
    enum:
      - number
      - integer
      - string
      - datetime
      - url
      - boolean
      - TBD
  enumType:
    type:
      array
    description: |
      enumType (an array - could be size 1; or a reference to value
      domain api). Reference to value domain could be a URL or a path
      that points to either a list of acceptable values or part of a
      set of MDF yaml files that define the value domain (term list and defs)
    items:
      anyOf:
        -
          type:
            string
        -
          $ref:
            "#/defs/url"
        -
          $ref:
            "#/defs/path"
    uniqueItems: true
  numberWithUnits:
    $id: "#numberWithUnits"
    type: object
    description: |
      numberWithUnits must have a "value_type" which is either "integer" or
      "number", and a "units" property,which can be a singleton array of a simple string (e.g. "mg"),
      or a regex ( "pattern" : ^<regexp>$ ), or an enumeration (array of allowed
      units strings, or ref to the term server)
    properties:
      value_type:
        type: string
        enum:
          - integer
          - number
      units:
        oneOf:
          -
            type: array
            items:
              -
                $ref: "#/defs/regex"
            uniqueItems: true
          -
            $ref: "#/defs/enumType"
      Tags:
        $ref: "#/defs/tagsSpec"
    required:
      - value_type
      - units
  listType:
    $id: "#listType"
    type: object
    description: |
      listType indicates that such a value should be instantiated as a list or array of
      scalar values. The type each of the scalar values should take is provided by the
      "item_type" property defined here. The item_type can be any of the scalar types
      defined in this schema. A listType of { "value_type":"list", "items": <an enumType> }
      would indicate that the data value should consist of an array of strings, each
      string coming from the specified enum of acceptable values.
    properties:
      value_type:
        const: list
      item_type:
        oneOf:
          -
            $ref: "#/defs/simpleType"
          -
            $ref: "#/defs/enumType"
          -
            $ref: "#/defs/numberWithUnits"
      Enum:
        $ref: "#/defs/enumType"
      Tags:
        $ref: "#/defs/tagsSpec"
    oneOf:
      -
        required:
          - value_type
          - item_type
      -
        required:
          - value_type
          - Enum
  tagsSpec:
    $id: "#tagsSpec"
    type: object
    additionalProperties:
      oneOf:
        - type: string
        - type: number
        - type: boolean
  nodeSpec:
    $id: "#nodeSpec"
    type: object
    properties:
      Props:
        oneOf:
          -
            type: array
            items:
              $ref: "#/defs/snake_case_id"
            uniqueItems: true
          -
            type:
              "null"
      Desc:
        description: |
          Human-readable description of the node.
        type: string
      Tags:
        $ref: "#/defs/tagsSpec"
      Term:
        description: |
          If a Node is representative of an entity or concept in an 
          external authority, the terminology, code, and authority
          can be noted in this entry.
          This field is list-valued - multiple terms may be provided.
        type: array
        items:
          $ref: "#/defs/termSpec"
        uniqueItems: true
      NanoID:
        $ref: "#/defs/nanoid"
    required:
      - Props
  relnSpec:
    $id: "#relnSpec"
    type: object
    properties:
      Desc:
        description: |
          Human-readable description of the relationship.
        type: string
      Mul:
        # here, the "default" multiplicity for all Src->Dst pairs
        type: string
        enum:
          - one_to_one
          - one_to_many
          - many_to_one
          - many_to_many
      Props:
        oneOf:
          -
            type: array
            items:
              $ref: "#/defs/snake_case_id"
            uniqueItems: true
          -
            type:
              "null"
      Ends:
        type: array
        items:
          type: object
          properties:
            Src:
              $ref: "#/defs/snake_case_id"
              # and need to be nodes defined in Nodes:
            Dst:
              $ref: "#/defs/snake_case_id"
              # and need to be nodes defined in Nodes:
            Mul:
              # here, Src->Dst specific multiplicity
              # overrides default above
              type: string
              enum:
                - one_to_one
                - one_to_many
                - many_to_one
                - many_to_many
            Tags:
              $ref: "#/defs/tagsSpec"
          uniqueItems: true
          required:
            - Src
            - Dst
      Tags:
        $ref: "#/defs/tagsSpec"
      Term:
        description: |
          If a Relationship is representative of an entity or concept in an 
          external authority, the terminology, code, and authority
          can be noted in this entry.
          This field is list-valued - multiple terms may be provided.
        type: array
        items:
          $ref: "#/defs/termSpec"
        uniqueItems: true
      NanoID:
        $ref: "#/defs/nanoid"
    required:
      - Props
      - Mul
      - Ends
  propSpec: 
    $id: "#propSpec"
    type: object
    properties:
      Desc:
        description: |
          Human-readable description of the property.
        type: string
      Src:
        description: |
          Source of data values: external submitter, internal curation, or
          automatically computed.
        type: string
      Key:
        description: |
          A boolean value. True indicates that the containing property is
          or can be used as a unique identifier for the containing node
          instances. Useful for downstream data applications (database
          loading, e.g.).
      Nul:
        type: boolean
        description: |
          A boolean value (default False). Whether or not a property can accept
          null as a valid value.
      Req:
        description: |
          A boolean value (default False or \'No\'). Whether or not data _must_ include a
          value for the property. The value \'Preferred\' indicates that submitters should
          submit data for the property if they have the data.
        oneOf:
          -
            type: boolean
          -
            type: string
            enum:
              - "Yes"
              - "No"
              - "Preferred"
      Deprecated:
        description: |
          True if this property is being retained for backward compatibility,
          but should not be used in new models.
        type: boolean
      Strict:
        description: |
          A boolean value (default True). This attribute is intended as a hint to validation
          code. If True, data values should adhere strictly to the Type/Enum specified for
          the property. If False, the validation should be \'less strict\', the interpretation
          of which is use case-dependent. The primary reason for this attribute is to indicate
          that validation should not fail on an Enum-valued property when the data value is not
          found in the specified Enum. This is useful when the acceptable value list has not
          been solidified in initial development.
        type: boolean
      Type:
        description: |
              Property values can have (1) simple types (number, integer, string
              datetime, or --if necessary-- \'TBD\'; (2) a number_with_units type
              (e.g., { \"value_type\":\"integer\", \"units\":\"mm\" }); (3) a regular
              expression that a (string) value must match; (4) an enumeration
              of acceptable values, or a url or path fragment to an api that will validate against
              such a list.
        oneOf:
          -
            $ref: "#/defs/simpleType"
          -
            $ref: "#/defs/numberWithUnits"
          -
            $ref: "#/defs/regex"
          -
            $ref: "#/defs/url"
          -
            $ref: "#/defs/listType"
          -
            $ref: "#/defs/enumType"
      Enum:
        description: |
              Same as Type:[<strings>], defines an enumeration. This keyword is meant to assist
              readability. Either one of Type or Enum may be present in a property definition,
              but not both.
        $ref: "#/defs/enumType" 
      Tags:
        $ref: "#/defs/tagsSpec"
      Term:
        description: |
          If a Property is representative of an entity or concept in an 
          external authority, the terminology, code, and authority
          can be noted in this entry.
          This field is list-valued - multiple terms may be provided.
        type: array
        items:
          $ref: "#/defs/termSpec"
        uniqueItems: true
      NanoID: 
        $ref: "#/defs/nanoid"
    oneOf:
      -
        required:
          - Type
      -
        required:
          - Enum
  termSpec:
    $id: "#termSpec"
    type: object
    properties:
      Handle:
        description: |
          This is a human-readable short name for the Term, that can be but is not
          necessarily the Value; it should be understood as a token that can be used
          to refer to this Term object. In the Terms subsection, the Handle should be
          inferred from the key assigned to the Term object. For the Term attribute of
          entities, the Handle may be explictly defined with the Handle key, otherwise
          the implicit handle should be identical with the Value.
      Desc:
        description: |
          Human-readable, non-normative description of this term.
        type: string
      Value:
        description: |
          The string value used in data representations of the term. Can be, but is not
          necessarily, the term "handle", i.e. the key for the term in the Terms object.
          See Handle key above.
        type: string
      Origin:
        description: |
          A (standardized) abbreviation desiginating the authority, source, or "coiner"
          of the term, reponsible for maintaining its definition and value representation.
          Example: NCIt for the NCI Thesaurus, DICOM.
        type: string
      Code:
        description: |
          An identifier assigned to the term by the authority given in the Origin field.
          Examples: NCIt concept code, ontology CURIE, caDSR CDE ID.
        type: string
      Version:
        description: |
          Version of this term according to the authority given in the Origin field.
        type: string
      Tags:
        $ref: "#/defs/tagsSpec"
      Definition:
        description: |
          Text definition for the term, ideally as provided by the authority
          given in the Origin field.
        type: string
      NanoID:
        $ref: "#/defs/nanoid"
    required:
      - Value
      - Origin