Skip to content

Latest commit

 

History

History
89 lines (77 loc) · 2.84 KB

MODEL-GUIDE.md

File metadata and controls

89 lines (77 loc) · 2.84 KB
Raw

Specifications

Keyword guide

The build script will enforce the following keyword conventions.

  • naming

    • property names MUST be snake_case
    • schema object names MUST be PascalCase (upper camel case)
    • enum names MUST be lowercase with underscores at natural word breaks. Valid characters are ^[a-z0-9_]+$. Enum names MUST start with an alphabetic character.
      • NO: 100_gpbs
      • YES: one_hundred_gbps
    • namespaces MUST be PascalCase (upper camel case) and use a . separator

  • oneOf

    • oneOf OpenAPI keyword support in generation tools is not very well supported at this time
    • this repository uses the choice property to discriminate between multiple objects at the same level 
      # demonstrates how to model a choice
    Port:
        type: object
        required: [choice]
        properties:
            choice:
                type: string
                enum: [physical, interface, virtual, container]
            physical:
                $ref: '#/components/schemas/Physical'
            interface:
                $ref: '#/components/schemas/Interface'
            virtual:
                $ref: '#/components/schemas/Virtual'
            container:
                $ref: '#/components/schemas/Container'

  • allOf

    • is not to be used
    • use the x-inline extension instead and the bundler will do inline replacement

  • description

    • everything MUST have a description keyword filled in with a meaningful description

  • schema

    • top level schema objects should avoid properties as simple datatypes and strive to encapsulate those properties in an object to allow for future extensiblity

  • nullable

    • MUST NOT be used

  • x-inline

    • use x-inline to inline snippets into a schema
    • the bundler.py will correctly inline and drop the x-inline-properties
    components:
x-inline:
    name:
    description: >-
        The primary key for any item to be used in a list or as a
        foreign key reference
    type: string
    pattern: ^[\sa-zA-Z0-9-_()><\[\]]+$

  • x-constraint

    • use x-constraint to identify referential integrity targets
    • use yamlpath to specify a constraint within an openapi yaml document
    • an implementation of the model should use this extension to enforce referential integrity
    • example: constrain a property so that it only contains a Port name
    property:
    port_name:
        type: string
        x-constraint:
        - /components/schemas/Port.properties.name