From 0cd73e91544f1af2f39b2c5ed963e1b2e25eba89 Mon Sep 17 00:00:00 2001 From: "Mark T. Voelker" Date: Mon, 14 Sep 2015 14:19:36 -0400 Subject: [PATCH] Define Schema 1.4 As we've begun using Schema 1.3, we've found a couple of minor issues with it. First, 1.3 has a duplicate source of truth for the status (required, advisory, deprecated, removed) of a Capability: there's a status field in the Capability definition itself, and there are lists in the Components block of which Capabilities are required, advisory, deprecated, and removed. This patch removes the status field from the Capability block as RefStack currently ignores it anyway [1] (making this the least-breaking option of the two). Second, we've identified the need for the next proposed Guideline to have a static filename, but also let people know when it's being targetted for a vote by the Board of Directors.[2][3] I've added a new field to provide that. [1] See Paul Van Eck's comment in https://review.openstack.org/#/c/217393/ [2] See Chris Hoge and Mark Voelker's comments in: https://review.openstack.org/#/c/223234/ [3] https://review.openstack.org/#/c/223243/ Change-Id: I6102f2b5b0e6eec7ce2ca36249cf0e3bd281d7ef --- doc/source/schema/1.4.rst | 108 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 doc/source/schema/1.4.rst diff --git a/doc/source/schema/1.4.rst b/doc/source/schema/1.4.rst new file mode 100644 index 00000000..1b9c2be6 --- /dev/null +++ b/doc/source/schema/1.4.rst @@ -0,0 +1,108 @@ +JSON Schema v1.4 +==================== + +Changes from v1.3 + +: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 + + +.. code-block:: json + + { "id": "2016.01", # Spec name (date based) + "schema": "1.4", # Schema version + "reference": "http://github.com/openstack/defcore/schema.1.4.rst", # Schema description + "source": "http://git.openstack.org/cgit/openstack/defcore/", # git repo for files + "status": "approved", # can be draft, review, approved or superseded [see 2015B C6.3] + "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 array + "compute", "object" + ], + "advisory": [], # incoming array + "deprecated": [], # outgoing array + "removed": [] # removed array + }, + "components": { # components detail + "compute": { # component name + "required": [ # required array + "compute-auth" + ], + "advisory": [ # incoming array + "compute-servers-metadata" + ], + "deprecated": [], # outgoing array + "removed": [ # removed array + "volume" + ] + }, + }, + "test-repositories": { # tracks difference possible test sources + "tempest": { # source of tests + "git-sha": "c77e46d8e3", # reference for automated checkout + "url": "https://git.openstack.org/cgit/openstack/tempest/" # git location from OpenStack + } + }, + "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 + "guidelines" : ["deprecated"] # deprecated DO NOT USE + "required-since" : "2015.05" # guideline where capability became required, "" if not required + "description" : "Helpful Description", + "flagged" : [], # deprecated DO NOT USE, moved under test + "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 + "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 } + } + }