==================================================== The OpenStack Interoperability Guideline Format v2.0 ==================================================== The following document describes the organization and formatting of each section and subsection of the guideline format. metadata -------- Information about the schema version, the id, scoring, board approval process, and other information. id ~~ The string identifier of guideline. Typically for the OpenStack Interop Working group it refers to the date and month of approval (for example `2017.08`), and `next` for the current proposed working guideline. schema ~~~~~~ A reference to the schema used to validate the guideline. reference ~~~~~~~~~ The URL of the guideline. source ~~~~~~ The URL of the repository where the guideline is hosted. scoring ~~~~~~~ An optional section that described the criteria used to score the capabilities. cutoff_score ```````````` The minimum score a capability needs to be considered for inclusion into the interoperability standard. criteria ```````` A list of the criteria, with each criteria made up of a: name The name of the criteria description A short description of the criteria weight An integer weight to assign the criteria os_trademark_approval ~~~~~~~~~~~~~~~~~~~~~ Information related to board approval of guidelines for the OpenStack Powered Trademark Program. Required for board-approved guidelines, optional and not required for independent guidelines. Consists of: target_approval The target approval date for the guideline. replaces The ID of the guidelines this guideline replaces releases An array of OpenStack release names the guideline covers. status The current approval status of the guideline. platforms --------- A dictionary of all of the Platform objects that are defined in this guideline. A Platform is a standalone collection of components that provides some major set of services. For example, OpenStack Powered Platform offers all of the core OpenStack services: identity, compute, networking, image storage, block storage, and object storage. description ~~~~~~~~~~~ An optional description of the platform. components ~~~~~~~~~~ A list of all of the components that belong in this platform. Each component is an object with the following two fields: name The name of the component, should match the name of the component defined in this document or in the optional source field. source Optional, a reference to the guideline where the component is defined. add-ons ---------- A dictionary of all of the add-on objects that are defined in this guideline. add-ons are collections of capabilities that provide additional services and functionality on top of an existing platform. An example might be orchestration on top of OpenStack Powered Platform. In addition to defining what capabilities make up the add-on, components that are required to be present for the program to run may be specified. In this way, implicit compatibility with multiple platforms can be established. For example, a DNS add-on might require a compute component to work, but not a storage component. This would make that particular add-on implicitly compatible with OpenStack Powered Platform and OpenStack Powered compute, but not OpenStack Powered Storage. description ~~~~~~~~~~~ An optional description of the add-on. components ~~~~~~~~~~ A list of all of the components that belong in this add-on. Each component is an object with the following two fields: name The name of the component, should match the name of the component defined in this document or in the optional source field. source Optional, a reference to the guideline where the component is defined. required_platform_components ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A list of all of the components that are required to be present in the host platform for the add-on. Each component is an object with the following two fields: name The name of the component, should match the name of the component defined in this document or in the optional source field. source Optional, a reference to the guideline where the component is defined. optional_platform_components ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A list of all of the components that, if present in the host platform, is compatible with this add-on. Each component is an object with the following two fields: name The name of the component, should match the name of the component defined in this document or in the optional source field. source Optional, a reference to the guideline where the component is defined. components ---------- A component is a collection of capabilities and designated sections, that is used to constuct a complete set of services. For example, the `storage` component may collect a full set of capabilities needed to run Swift Object Storage, including capabilities from both the Swift project and the Keystone project (for identity services). capabilities ~~~~~~~~~~~~ An object with lists of capabilities, classified according to their approval status. The capability names must appear in this guideline, or in another referred guideline. required An array of capabilities that are required to be present for interoperability according to the guideline. advisory An array of capabilities that are being considered for inclusion in the next guideline release. deprecated An array of capabilities that may be present within an interoperable product, but should not be depended on, may not work, and will be removed. removed An array of capabilities that were required or deprecated in the former guideline, but have not been removed. designated_sections ~~~~~~~~~~~~~~~~~~~ An object with lists of designated sections, classified according to their approval status. The designated section names must appear in this guideline or in another referred guideline. required An array of that are required to be present for interoperability according to the guideline. advisory An array of that are being considered for inclusion in the next guideline release. deprecated An array of that may be present within an interoperable product, but should not be depended on, may not work, and will be removed. removed An array of that were required or deprecated in the former guideline, but have not been removed. capabilities ------------ A collection of capability definitions, indexed by the capability name. This section describes the content of a capability definition. achievements ~~~~~~~~~~~~ A list of criteria, defined in the scoring section of this guideline, that this capability meets. admin ~~~~~ A boolean that indicates if the capability requires administrator access. required_since ~~~~~~~~~~~~~~ An optional field that references the id of the guideline of when this capability was first required. description ~~~~~~~~~~~ A description of the capability. project ~~~~~~~ A reference to the project in the designated section for which the code that provides this capability can be found. tests ~~~~~ An dictionary of tests that the a product must pass to be considered to have this capability available. All tests that aren't flagged must be passed. Each test is indexed by its fully qualified test name. test definition ``````````````` A test an object that can identify the location of a test, even if that test has moved in a code repository. It has: idempotent_id A UUID attached to the test that will not change, even if the test is moved during refactoring. aliases An optional array of fully qualified test names. Used to locate tests different versions of the same test suite, in case of test refactoring flag An object that if present, indicates a problem with the test that changes its status from must-pass to optional-pass. flag ^^^^ A flag has the following fields: date When the flag was added to the test. reason A reason for why the test was flagged. action What action will be taken to resolve the flag, including but not limited to fixing the test in the upstream test suite, or removing it from the capability in a future guideline. designated_sections ------------------- A dictionary of designated sections, indexed by project name, that describe what code must be present for a product to be considered an OpenStack project. Within the project object, there is further indexing broken down by the section status, which is one of the following values: required The code is required to be in the product. advisory The code is scheduled to be required in the next release. deprecated The code will not be required in a future release. removed The code was previously required, is no longer required informational The code is not required, with commentary on why. Each section status object has the following fields, and also a collection if sections indexed by name. guidance Information on what the code does. comment Optional additional commentary on the project code. section ~~~~~~~ A section has the following fields: description A description of the code section. designated A boolean, true if the code must be present. A section is generally not made designated if there is a choice of upstream or third party providers for that capability. comment Optional additional commentary on the section. test_repositories ----------------- A dictionary of test repositories that provide the tests for the capabilities, indexed by name. A test repository object has the following fields: repository The URL of the repository where the tests are located. reference A reference to the release name, branch, or sha that the guideline was developed against. description An optional description of the repository.