DefCore Schema v1.5 Change Log

Changes from v1.4

change

move to formal json schema.

Changes from v1.3

change

update the aliases field description

added

aliases field in test block

added

cutoff_score

added

target_approval

removed

Status field in Capability blocks (as it duplicates the information already present in the Components list)

Changes from v1.2

added

reference

added

tests-repositories

added

required-since

added

tests now have block including idempotent_id and (optional) flagged information

change

guidelines to point to required-since

change

tests from array to hash

change

add hash after test-name keys

change

flagged points to new location tests/test-name/flagged

change

new version 1.3

Annotated Sample

Schema sample and annotations for reference only. Full schema follows.

{ "id": "2016.01",          # Spec name (date based)
  "schema": "1.5",          # Schema version
  "reference": "http://github.com/openstack/defcore/schema.1.4.rst",
                            # Schema description
  "source": "http://opendev.org/openstack/defcore/",
                            # git repo for files
  "status": "approved",     # can be draft, review, approved or superseded [see 2015B C6.3]
  "cutoff_score": "74",     # the minimum score a Capability must achieve to be required in this Guideline
  "target_approval": "2016-01-27",
                            # Target date for BoD to approve Guideline
  "replaces": "2015.07",    # previous spec
  "releases": ["icehouse"], # array of releases, lower case (generally three releases)
  "platform": {             # platform components
    "required": [           # required component array
      "compute", "object"
    ],
    "advisory": [],         # incoming component array
    "deprecated": [],       # outgoing component array
    "removed": []           # removed component array
  },
  "components": {           # components detail
    "compute": {            # component name
      "required": [         # required component array
        "compute-auth"
      ],
      "advisory": [         # incoming component array
        "compute-servers-metadata"
      ],
      "deprecated": [],     # outgoing component array
      "removed": [          # removed component array
        "volume"
      ]
    },
  },
  "test-repositories": {    # tracks difference possible test sources
    "tempest": {            # source of tests
      "git-sha": "c77e46d8e3",
                            # reference sha for automated checkout of known working release
      "url": "https://opendev.org/openstack/tempest/"
                            # repository location
    }
  },
  "criteria" : {            # explains achievements
    "core01" : {
      "Description" : "blah blah blah",
      "name" : "readable core01",
                            # allows more readable name than key
      "weight": 8           # total of all weights must be 100
    },
  }
  "capabilities": {         # capabilities listed in components
    "example-cap" : {       # capability key (cross reference to components required)
      "achievements" : ["core01"],
                            # array of criteria met.  must be one of items from "criteria" section
      "admin" : false,      # boolean designating whether an admin API is required
      "required-since" : "2015.05"
                            # guideline where capability became required, "" if not required
      "description" : "Helpful Description",
      "name" : "Friendly Short Name",
      "tests" : {           # hash of tests (use unique names)
        "tempest.api.project.file.class.test_name" : {
                            # test ID
          "idempotent_id" : "id-123-456",  # internal test identifier to track changes if test is moved
          "aliases" : [],   # A list of other names used to identify the same test, as sometimes
                            # test names change due to refactoring in Tempest. The name used as
                            # the key in the hash should be the name of the test as it was at the
                            # time the guideline was approved. Thus if this is a future guideline,
                            # move the old name here and put the new name as the hash key. If this
                            # is an approved guideline, then the new name goes in this list.
          "flagged" : {     # This section is required only if the test is flagged
            "reason" : "why this test was flagged",
                            # required to support flag request
            "action" : "proposed action to resolve",
                            # required path to resolve flag
            "date" : "yyyy-mm-dd"
                            # date flag was proposed (not approved)
          }
        },
      },
    },
  },
  "designated-sections" : {                 # designated sections
    "required" : {                          # sections that are required for this Guideline
      "nova" : {                            # project name
        "guidance": "short description",    # general information providing actionable detail
        "comment": "optional rationale",    # additional clairification
        "sections": {                       # hash of sections, project specific
          "section": {                      # key / name of a section
            "description": "useful detail", # expand on key in useful way
            "designated": false,            # boolean.  true if designated.  must align with guidance
            "comment": "none provided"      # optional details
          }
        }
      }
    },
    "advisory" : {},       # not required in this Guideline but may be required in a future guideline
    "deprecated" : {},     # no longer required in this Guideline and will be removed in futur Guidelines
    "removed" : {}         # no longer required and have been removed since the last Guideline
  }
}

JSON Schema Definition

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "id": "http://opendev.org/openstack/defcore/doc/source/schema/1.5.json",
  "type": "object",
  "required": [
    "id",
    "schema",
    "reference",
    "source",
    "status",
    "replaces",
    "target_approval",
    "releases",
    "platform",
    "components",
    "capabilities",
    "designated-sections",
    "criteria"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "schema": {
      "type": "string"
    },
    "reference": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "status": {
      "enum": [ "draft", "advisory", "approved", "superseded" ]
    },
    "replaces": {
      "type": "string"
    },
    "target_approval": {
      "type": "string",
      "pattern": "\\d{4}-\\d{2}-\\d{2}"
    },
    "releases": {
      "type": "array",
      "items": {
          "type": "string",
          "minItems": 1,
          "uniqueItems": true
      }
    },
    "platform": {
      "type": "object",
      "properties": {
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "advisory": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "deprecated": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "removed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "components": {
      "type": "object",
      "patternProperties": {
        "^\\w+$": {
          "$ref": "#/definitions/component"
        }
      },
      "additionalProperties": false
    },
    "capabilities": {
      "type": "object",
      "patternProperties": {
        "^\\w+$": {
          "$ref": "#/definitions/capabilty"
        }
      }
    },
    "designated-sections": {
      "type": "object",
      "required": [ "required", "advisory", "deprecated", "removed", "informational" ],
      "properties": {
        "required": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/designated-section"
            }
         }
        },
        "advisory": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/designated-section"
            }
          }
        },
        "deprecated": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/designated-section"
            }
          }
        },
        "removed": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/designated-section"
            }
          }
        },
        "informational": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/designated-section"
            }
          }
        }
      },
      "additionalProperties": false
    },
    "criteria": {
      "type": "object",
      "patternProperties": {
        "^\\w+$": {
          "$ref": "#/definitions/criteria"
        }
      },
      "additionalProperties": false
    }
  },
  "definitions": {
    "component": {
      "type": "object",
      "required": [ "required", "advisory", "deprecated", "removed" ],
      "properties": {
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "advisory": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "deprecated": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "removed": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "capability": {
      "type": "object",
      "required": [ "achievements",
        "admin",
        "description",
        "project",
        "require-since",
        "tests"
      ],
      "properties": {
        "achievements": {
          "type": "array",
          "items": {
            "enum": [
              "foundation",
              "complete",
              "proximity",
              "clients",
              "discover",
              "sticky",
              "future",
              "atomic",
              "stable",
              "tools",
              "deployed",
              "TODO ADD LAST ITEM HERE"
            ],
            "uniqueItems": true
          }
        },
        "admin": {
          "type": "boolean"
        },
        "description": {
          "type": "string"
        },
        "project": {
          "type": "string"
        },
        "required-since": {
          "type": "string",
          "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$"
        },
        "tests": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "$ref": "#/definitions/test"
            }
          }
        }
      }
    },
    "criteria": {
      "type": "object",
      "required": [ "Description", "name", "weight" ],
      "properties": {
        "Description": {
          "type": "string"
        },
        "name":  {
          "type": "string"
        },
        "weight": {
          "type": "integer"
        }
      }
    },
    "test": {
      "type": "object",
      "required": [ "idempotent_id" ],
      "properties": {
        "idempotent_id": {
          "type": "string"
        },
        "flagged": {
          "type": "object",
          "required": [ "reason", "action", "date" ],
          "properties": {
            "reason": {
              "type": "string",
              "pattern": "^D\\d{3} \\w+"
            },
            "action": {
              "type": "string"
            },
            "date": {
              "type": "string",
              "pattern": "\\d{4}-\\d{2}-\\d{2}"
            }
          }
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "uniqueItems": true
        }
      }
    },
    "designated-section": {
      "type": "object",
      "required": [ "guidance", "comment", "sections" ],
      "properties": {
        "guidance": {
          "type": "string"
        },
        "comment": {
          "type": "string"
        },
        "sections": {
          "type": "object",
          "patternProperties": {
            "^\\w+$": {
              "type": "object",
              "required": [ "description", "designated", "comment" ],
              "properties": {
                "description": {
                  "type": "string"
                },
                "designated": {
                  "type": "boolean"
                },
                "comment": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}