From 41cd98396485c939bed54f04854c32260888bb1d Mon Sep 17 00:00:00 2001 From: Paul Sherwood Date: Sun, 21 Feb 2016 04:36:15 +0000 Subject: Move content to schemas directory --- README.schemas | 137 -------------------- baserock.owl | 295 ------------------------------------------- chunk.json-schema | 116 ----------------- cluster.json-schema | 64 ---------- defaults.json-schema | 66 ---------- schemas/README.schemas | 137 ++++++++++++++++++++ schemas/baserock.owl | 295 +++++++++++++++++++++++++++++++++++++++++++ schemas/chunk.json-schema | 116 +++++++++++++++++ schemas/cluster.json-schema | 64 ++++++++++ schemas/defaults.json-schema | 66 ++++++++++ schemas/stratum.json-schema | 99 +++++++++++++++ schemas/system.json-schema | 59 +++++++++ stratum.json-schema | 99 --------------- system.json-schema | 59 --------- 14 files changed, 836 insertions(+), 836 deletions(-) delete mode 100644 README.schemas delete mode 100644 baserock.owl delete mode 100644 chunk.json-schema delete mode 100644 cluster.json-schema delete mode 100644 defaults.json-schema create mode 100644 schemas/README.schemas create mode 100644 schemas/baserock.owl create mode 100644 schemas/chunk.json-schema create mode 100644 schemas/cluster.json-schema create mode 100644 schemas/defaults.json-schema create mode 100644 schemas/stratum.json-schema create mode 100644 schemas/system.json-schema delete mode 100644 stratum.json-schema delete mode 100644 system.json-schema diff --git a/README.schemas b/README.schemas deleted file mode 100644 index a778918..0000000 --- a/README.schemas +++ /dev/null @@ -1,137 +0,0 @@ -Schemas for the Baserock definitions format -=========================================== - -The starting point for learning about the Baserock definitions format is the -wiki page at . - -The schemas/ directory in the Baserock reference definitions.git repository is -the canonical home for some schemas which describe the format in a -machine-readable way. - -There are two parts to 'Baserock definitions'. The 'Baserock data model' is an -abstract vocabulary for describing how to build, integrate and deploy software -components. The 'Baserock definitions YAML representation format' is a -serialisation format for the data model, which lets you write YAML files -describing how to build, integrate and deploy software components. - -If you want to make the YAML files easier to deal with, you only need -to care about the JSON-Schema schemas and anything that parses the YAML files. - -If you want to write a new tool to build, visualise, analyse or otherwise -process Baserock definitions in some way, you can ignore the syntax altogether, -use a pre-existing parser, and just think in terms of the data -model. - -If you want to change the data model, you still have quite a difficult job, -but at least it should be simple to write a translation layer on top of an -existing parser so that you can interpret all the existing Baserock reference -system definitions in terms of your new data model. - - -The Baserock definitions YAML representation format ---------------------------------------------------- - -YAML itself is a syntax for representating data as text. The YAML specification -is at . - -The data needs to be structured in a certain way for it to make sense as -Baserock build/integration/deployment instructions. We have used JSON-Schema -to describe the required layout of the data. - -The JSON-Schema standard is described at . The -JSON-Schema language was designed for use with JSON, which is another syntax -for representing data as text, which happens to be a subset of YAML. We have -found so far that JSON-Schema works well with YAML, at least when using the -Python 'jsonschema' module. - -Definitions are represented by files with a '.morph' extension. There are four -different kinds: 'chunk', 'stratum', 'system', and 'cluster'. Each of these is -described with a different .json-schema file. It is possible to merge all these -into one file, and use the 'oneOf' field to say that any .morph file should -match exactly one of the layouts. The only issue with this approach is that -the Python 'jsonschema' model will give you totally useless errors if anything -is invalid (along the lines of " is not valid under any of -the given schemas"). So for now they are separate. - - -Tools for working with the Baserock YAML schemas ------------------------------------------------- - -You can use `scripts/yaml-jsonschema` to validate .morph files against the -schemas. For example: - - scripts/yaml-jsonschema schemas/cluster.json-schema clusters/*.morph - - -The Baserock data model ------------------------ - -The best way to represent information on disk may be a pretty inefficient way -to represent that data in a computer's memory. Likewise, the way a program -stores data internally may be totally impractical for people to edit directly. - -The file `baserock.owl` is an initial effort to describe the Baserock data -model independently of any syntax or representation. - -We use the W3C standard Web Ontology Language (OWL), combined with the much -simpler RDF Schema language. Together, this allows defining the vocabulary we -can use to define build, integration and deployment instructions. There are -various ways to represent OWL 'ontologies'; `baserock.owl` uses a -representation format named Turtle, which is designed to be convenient for -hand-editing. - -The current data model is very closely tied to the current syntax, but we are -looking to change this and make it much more generic. This will involve -removing the current 'Chunk', 'Stratum', 'System' and 'Cluster' classes, and -adding something like 'thing with build instructions' and 'thing that contains -other things' instead. Name suggestions are welcome :-) - -It's useful to consider existing OWL and RDF Schema vocabularies that are -related to the Baserock data model. In future we can link the Baserock -reference system definitions with related data published elsewhere on the Web. -Here is an incomplete list: - - - Description of a Project (DOAP): https://github.com/edumbill/doap - - Software Ontology: https://robertdavidstevens.wordpress.com/2014/06/19/the-software-ontology-swo/ - - Software Packet Data Exchange (SPDX): https://spdx.org/about-spdx/what-is-spdx - - -Tools for working with the Baserock data model schema ------------------------------------------------------ - -It's difficult to find to a short, relevant 'getting started' guide. The -website http://www.linkeddata.org/ has a lot of background that should be -useful. - -The `rapper` commandline tool, which comes as part of the 'raptor2' C library, -is helpful for converting from one syntax to another, and checking if -`baserock.owl` is valid Turtle syntax. The 'raptor2' homepage is -. - -To check the syntax of `baserock.owl` using `rapper`: - - rapper -i turtle schemas/baserock.owl - - -Omissions / TODO items ----------------------- - -- Device nodes: chunk .morph files can list a set of device nodes. In - `chunk.json-schema` this is recognised, but in `baserock.owl` it is missing. - -- 'Lorry' mirroring instructions. These contain information on where 'upstream' - source code is kept, which should be considered part of the data model. A - JSON schema may be better off in lorry.git or - baserock/local-config/lorries.git. - -- Metadata in built systems. This is currently not standardised at all. - - -Comments --------- - -As far as I know, Baserock is the first project to treat build, integration and -deployment instructions as data rather than code. If you have questions about -the schemas, the definitions format, or the overall approach, and they aren't -answered here or in , then please ask on -the baserock-dev@baserock.org mailing list. diff --git a/baserock.owl b/baserock.owl deleted file mode 100644 index 33113d8..0000000 --- a/baserock.owl +++ /dev/null @@ -1,295 +0,0 @@ -# Copyright (C) 2015 Codethink Limited -# -# This program is free software; you can redistribute it and/or modify -# it under the terms of the GNU General Public License as published by -# the Free Software Foundation; version 2 of the License. -# -# This program is distributed in the hope that it will be useful, -# but WITHOUT ANY WARRANTY; without even the implied warranty of -# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -# GNU General Public License for more details. -# -# You should have received a copy of the GNU General Public License along -# with this program. If not, see . - - -# This schema describes the Baserock data model. It describes how the data -# can be represented in computer memory, it doesn't specify anything about -# how it should be stored on disk or transferred. -# -# Please see README.schemas, and http://wiki.baserock.org/definitions/current/ -# for more information. -# -# This is not a brilliant schema, in Linked Data terms, because it's using -# Baserock-specific terminology and a rigid layout, instead of being a generic -# vocabulary for describing how to assemble software. However, it maps closely -# to the format that the existing Baserock reference system definitions use. -# We hope to produce a simpler and more flexible 2.x version of this schema in -# future. - - -# Partial OWL and RDF Schema glossary: -# -# domain: the set of objects that a can have a property. -# range: the set of possible values for a property. -# -# ObjectProperty: -# a property whose value must be another resource. -# DatatypeProperty: -# a property whose value is one of the datatype defined by XML Schema ("xsd") -# FunctionalProperty: -# a property which can only have one value per resource -# InverseFunctionalProperty: -# a property which can only have one resource per value - - -# Metadata - -@prefix : . -@prefix owl: . -@prefix rdfs: . -@prefix rdf: . -@prefix xsd: . -@prefix dc: . - -: a owl:Ontology ; - dc:title "Schema for Baserock data model" ; - dc:creator "The Baserock Project" ; - # Versioned according to Semantic Versioning http://www.semver.org/ - owl:versionInfo "0.9.0" . - - -## Entities - -# Source definitions - -:Morphology a owl:Class ; - rdfs:comment "A definition file." . - -:Cluster a owl:Class ; - rdfs:subClassOf :Morphology ; - rdfs:comment "Instructions for deploying one or systems." ; - owl:disjointWith :System, :Stratum, :Chunk . - -:System a owl:Class ; - rdfs:subClassOf :Morphology ; - rdfs:comment "A collection of strata in a form that can be executed." ; - owl:disjointWith :Cluster, :Stratum, :Chunk . - -:Stratum a owl:Class ; - rdfs:subClassOf :Morphology ; - rdfs:comment "A set of related chunks." ; - owl:disjointWith :Cluster, :System, :Chunk . - -:Chunk a owl:Class ; - rdfs:subClassOf :Morphology ; - rdfs:comment "An individual component, that can be built from a Git repository." ; - owl:disjointWith :Cluster, :System, :Stratum . - -# Container contents - -:SystemDeployment a owl:Class ; - rdfs:comment "Information for deploying one system of a cluster." . - -:ChunkReference a owl:Class ; - rdfs:comment "An instance of a chunk within a stratum." . - -# Products (for artifact split rules). - -:Artifact a owl:Class ; - rdfs:comment "One part of the result of building a morphology. The output of a build is split according to patterns, so there are multiple artifacts produced for a given source." . - -:StratumArtifact a owl:Class ; - rdfs:subClassOf :Artifact ; - rdfs:comment "Part of the result of building a stratum." ; - owl:disjointWith :ChunkArtifact. - -:ChunkArtifact a owl:Class ; - rdfs:subClassOf :Artifact ; - rdfs:comment "Part of the result of building a chunk." ; - owl:disjointWith :StratumArtifact. - - -## Shared properties - -# 'name' becomes part of the URL when we import definition .morph files as RDF, -# so it doesn't need a property. - -# Use dc:description for 'description', see: -# http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-description - - -## Cluster-specific properties - -:containsSystemDeployment a owl:ObjectProperty ; - rdfs:domain :Cluster ; - rdfs:range :SystemDeployment ; - owl:minCardinality 1 . - - -## SystemDeployment-specific properties - -:deploysSystem a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :SystemDeployment ; - rdfs:range :System . - -:hasLabel a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :SystemDeployment ; - rdfs:range xsd:string . - -:hasType a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :SystemDeployment ; - rdfs:range xsd:string ; - rdfs:comment "The .write extension used to perform the deployment." . - -:hasLocation a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :SystemDeployment ; - rdfs:range xsd:string ; - rdfs:comment "Deployment location. This is passed to the selected .write extension" . - -# FIXME: this is actually a key-value mapping, how do you do that in RDF properly? -:hasConfigurationSetting a owl:DatatypeProperty ; - rdfs:domain :SystemDeployment ; - rdfs:range xsd:string ; - rdfs:comment "Arbitrary key=value pair that is set in the environment of the .configure and .write extensions during deployment." . - - -## System-specific properties - -:containsStratumArtifact a owl:ObjectProperty ; - rdfs:domain :System ; - rdfs:range :StratumArtifact ; - owl:minCardinality 1 . - -# A build tool will only understand a certain set of architectures, but I think -# that should not be part of the data model. -:hasArchitecture a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :System ; - rdfs:range xsd:string . - -:hasConfigurationExtension a owl:DatatypeProperty ; - rdfs:domain :System ; - rdfs:range xsd:string ; - rdfs:comment "A .configure extension to be run when with system is deployed." . - - -## Stratum-specific properties - -:producesStratumArtifact a owl:ObjectProperty , rdf:Seq ; - rdfs:domain :Stratum ; - rdfs:range :StratumArtifact ; - rdfs:comment "iDescribes how this artifact is split once all chunks are built." . - -:hasStratumBuildDependency a owl:ObjectProperty ; - rdfs:domain :Stratum ; - rdfs:range :Stratum . - -:containsChunkReference a owl:ObjectProperty ; - rdfs:domain :Stratum ; - rdfs:range :ChunkReference ; - owl:minCardinality 1 . - - -## ChunkReference-specific properties - -:refersToChunk a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range :Chunk . - -:repo a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range xsd:string ; - rdfs:comment "Git repo that this chunk's build instructions should be run in. Can be a keyed URL according to the repo-alias mapping, which isn't currently defined in this data model." . - -:ref a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range xsd:string ; - rdfs:comment "Ref of the Git repo that should be checked out before building. Usually a SHA1." . - -:unpetrifyRef a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range xsd:string ; - rdfs:comment "Name of the ref that should be checked out (useful when 'ref' is a SHA1 to keep track of the actual branch/tag name)." . - -:hasChunkBuildDependency a owl:ObjectProperty ; - rdfs:domain :ChunkReference ; - rdfs:range :Chunk . - -:prefix a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range xsd:string ; - rdfs:comment "Value of the PREFIX environment variable in the build environment (defaults to /usr)" . - -# FIXME: it's possible to specify in OWL that 'bootstrap' and 'normal' are the -# only valid values. -:buildMode a owl:DatatypeProperty , owl:FunctionalProperty ; - rdfs:domain :ChunkReference ; - rdfs:range xsd:string . - - -## Chunk-specific properties - -# build-system isn't included here, as it overlaps with the *-commands -# fields in an unfortunate way. - -# Note that representing lists of things in RDF is a bit of a pain. -# http://smiy.sourceforge.net/olo/spec/orderedlistontology.html might -# be worth investigating. - -:producesChunkArtifact a owl:ObjectProperty , rdf:Seq ; - rdfs:domain :Chunk ; - rdfs:range :ChunkArtifact ; - rdfs:comment "Describes how this artifact is split once built." . - -:maxJobs a owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range xsd:integer ; - rdfs:comment "Number of parallel jobs that can be run for this chunk. Only useful if set to 1, to mark components which have Makefiles that do not work with `make -j N`.". - -:CommandSequence a owl:Class ; - rdfs:subClassOf rdf:Seq ; - rdfs:comment "An ordered sequence of commands." . - -:preConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:configureCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:postConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:preBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:buildCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:postBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:preInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:installCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - -:postInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; - rdfs:domain :Chunk ; - rdfs:range :CommandSequence . - - -# Artifact properties - -:includes a owl:DatatypeProperty , rdf:Seq ; - rdfs:domain :Artifact ; - rdfs:range xsd:string ; - rdfs:comment "A regular expression pattern. The results of a build are matched against this pattern and any that match will be included in that artifact." . diff --git a/chunk.json-schema b/chunk.json-schema deleted file mode 100644 index 8de2fb5..0000000 --- a/chunk.json-schema +++ /dev/null @@ -1,116 +0,0 @@ -$schema: http://json-schema.org/draft-04/schema# -id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema - -description: | - This is a JSON-Schema description of a 'chunk' .morph file, which is part of - the Baserock definitions YAML representation format. - - This JSON-Schema file is valid for VERSION 7 of the Baserock definitions - YAML serialisation format. - - The Baserock definitions format is the recommended way of representing - Baserock definitions on disk. The actual data model is described separately. - See https://wiki.baserock.org/definitions for more information. - - This schema is represented as YAML, so that it can be edited more easily. - You may need to convert to JSON if using a JSON-Schema tool that expects - its input to be an actual string containing data serialised as JSON. - -definitions: - # Corresponds to CommandSequence in Baserock data model. - command-sequence: - type: array - items: { type: string } - - # Corresponds to DeviceNode in Baserock data model. - device-node: - type: object - required: [type, filename, gid, uid, major, minor, permissions] - properties: - type: { type: string } - filename: { type: string } - gid: { type: integer } - uid: { type: integer } - major: { type: integer } - minor: { type: integer } - permissions: { type: string } - - # Defines one or more instances of ChunkArtifact from the Baserock data model. - split-rules: - type: array - items: - type: object - - required: [artifact, include] - additionalProperties: false - - properties: - artifact: {type: string} - include: - type: array - items: - type: string - format: regex - - system-integration-commands: - type: object - patternProperties: - # The property name here should correspond to the name of the chunk's - # artifacts, probably the '-bins' artifact if you are using the normal - # splitting rules. - ^.*$: - type: object - patternProperties: - ^.*$: - $ref: "#/definitions/command-sequence" - -# Corresponds to Chunk in Baserock data model. -type: object - -additionalProperties: false -required: [ 'name', 'kind'] - -properties: - name: { type: string } - kind: { enum: [ "chunk" ] } - - description: { type: string } - - build-system: { type: string } - max-jobs: { type: integer } - - products: - $ref: "#/definitions/split-rules" - - pre-configure-commands: - $ref: "#/definitions/command-sequence" - configure-commands: - $ref: "#/definitions/command-sequence" - post-configure-commands: - $ref: "#/definitions/command-sequence" - pre-build-commands: - $ref: "#/definitions/command-sequence" - build-commands: - $ref: "#/definitions/command-sequence" - post-build-commands: - $ref: "#/definitions/command-sequence" - pre-install-commands: - $ref: "#/definitions/command-sequence" - install-commands: - $ref: "#/definitions/command-sequence" - post-install-commands: - $ref: "#/definitions/command-sequence" - pre-strip-commands: - $ref: "#/definitions/command-sequence" - strip-commands: - $ref: "#/definitions/command-sequence" - post-strip-commands: - $ref: "#/definitions/command-sequence" - - system-integration: - $ref: "#/definitions/system-integration-commands" - - devices: - type: array - items: - $ref: "#/definitions/device-node" diff --git a/cluster.json-schema b/cluster.json-schema deleted file mode 100644 index 1a628c7..0000000 --- a/cluster.json-schema +++ /dev/null @@ -1,64 +0,0 @@ -$schema: http://json-schema.org/draft-04/schema# -id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/cluster.json-schema - -description: - This is a JSON-Schema description of a 'cluster' .morph file, which is part - of the Baserock definitions YAML representation format. - - This JSON-Schema file is valid for VERSION 7 of the Baserock definitions - YAML serialisation format. - - The Baserock definitions format is the recommended way of representing - Baserock definitions on disk. The actual data model is described separately. - See https://wiki.baserock.org/definitions for more information. - - This schema is represented as YAML, so that it can be edited more easily. - You may need to convert to JSON if using a JSON-Schema tool that expects - its input to be an actual string containing data serialised as JSON. - -definitions: - # A reference to a System, plus one or more SystemDeployment for that system. - system-deployment-set: - type: object - - required: [ 'morph', 'deploy' ] - additionalProperties: false - - properties: - morph: { type: string } - deploy-defaults: - type: object - additionalProperties: true - deploy: - patternProperties: - ^.*$: { $ref: "#/definitions/system-deployment" } - subsystems: - type: array - items: { $ref: "#/definitions/system-deployment-set" } - - # Corresponds to SystemDeployment in Baserock data model. - system-deployment: - type: object - - required: [ 'type', 'location' ] - additionalProperties: true - - properties: - type: { type: string } - location: { type: string } - - -# Corresponds to Cluster in Baserock data model. -type: object - -#required: [ 'name', 'kind', 'systems' ] -additionalProperties: false - -properties: - name: { type: string } - kind: { enum: [ "cluster" ] } - description: { type: string } - - systems: - type: array - items: { $ref: "#/definitions/system-deployment-set" } diff --git a/defaults.json-schema b/defaults.json-schema deleted file mode 100644 index 2f71342..0000000 --- a/defaults.json-schema +++ /dev/null @@ -1,66 +0,0 @@ -$schema: http://json-schema.org/draft-04/schema# -id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/defaults.json-schema - -description: | - This is a JSON-Schema description of the DEFAULTS file specified in the - Baserock definitions format. DEFAULTS is a YAML file that contains global - defaults for a set of Baserock definitions. - - This JSON-Schema file is valid for VERSION 7 of the Baserock definitions - YAML serialisation format. - - The Baserock definitions YAML serialisation format is the recommended way of - representing Baserock definitions on disk. The actual data model is described - separately. See for more information. - - This schema is represented as YAML, so that it can be edited more easily. - You may need to convert to JSON if using a JSON-Schema tool that expects - its input to be an actual string containing data serialised as JSON. - -definitions: - command-sequence: - type: array - items: {type: string} - - build-system: - type: object - additionalProperties: false - properties: - build-commands: {$ref: '#/definitions/command-sequence'} - configure-commands: {$ref: '#/definitions/command-sequence'} - install-commands: {$ref: '#/definitions/command-sequence'} - strip-commands: {$ref: '#/definitions/command-sequence'} - - split-rules: - type: array - items: - type: object - - required: [artifact, include] - additionalProperties: false - - properties: - artifact: {type: string} - include: - type: array - items: - type: string - format: regex - -type: object -additionalProperties: false - -properties: - # Predefined build systems. - build-systems: - type: object - patternProperties: - ^.*$: {$ref: '#/definitions/build-system'} - - # Predefined artifact splitting rules. - split-rules: - type: object - additionalProperties: false - properties: - chunk: {$ref: '#/definitions/split-rules'} - stratum: {$ref: '#/definitions/split-rules'} diff --git a/schemas/README.schemas b/schemas/README.schemas new file mode 100644 index 0000000..a778918 --- /dev/null +++ b/schemas/README.schemas @@ -0,0 +1,137 @@ +Schemas for the Baserock definitions format +=========================================== + +The starting point for learning about the Baserock definitions format is the +wiki page at . + +The schemas/ directory in the Baserock reference definitions.git repository is +the canonical home for some schemas which describe the format in a +machine-readable way. + +There are two parts to 'Baserock definitions'. The 'Baserock data model' is an +abstract vocabulary for describing how to build, integrate and deploy software +components. The 'Baserock definitions YAML representation format' is a +serialisation format for the data model, which lets you write YAML files +describing how to build, integrate and deploy software components. + +If you want to make the YAML files easier to deal with, you only need +to care about the JSON-Schema schemas and anything that parses the YAML files. + +If you want to write a new tool to build, visualise, analyse or otherwise +process Baserock definitions in some way, you can ignore the syntax altogether, +use a pre-existing parser, and just think in terms of the data +model. + +If you want to change the data model, you still have quite a difficult job, +but at least it should be simple to write a translation layer on top of an +existing parser so that you can interpret all the existing Baserock reference +system definitions in terms of your new data model. + + +The Baserock definitions YAML representation format +--------------------------------------------------- + +YAML itself is a syntax for representating data as text. The YAML specification +is at . + +The data needs to be structured in a certain way for it to make sense as +Baserock build/integration/deployment instructions. We have used JSON-Schema +to describe the required layout of the data. + +The JSON-Schema standard is described at . The +JSON-Schema language was designed for use with JSON, which is another syntax +for representing data as text, which happens to be a subset of YAML. We have +found so far that JSON-Schema works well with YAML, at least when using the +Python 'jsonschema' module. + +Definitions are represented by files with a '.morph' extension. There are four +different kinds: 'chunk', 'stratum', 'system', and 'cluster'. Each of these is +described with a different .json-schema file. It is possible to merge all these +into one file, and use the 'oneOf' field to say that any .morph file should +match exactly one of the layouts. The only issue with this approach is that +the Python 'jsonschema' model will give you totally useless errors if anything +is invalid (along the lines of " is not valid under any of +the given schemas"). So for now they are separate. + + +Tools for working with the Baserock YAML schemas +------------------------------------------------ + +You can use `scripts/yaml-jsonschema` to validate .morph files against the +schemas. For example: + + scripts/yaml-jsonschema schemas/cluster.json-schema clusters/*.morph + + +The Baserock data model +----------------------- + +The best way to represent information on disk may be a pretty inefficient way +to represent that data in a computer's memory. Likewise, the way a program +stores data internally may be totally impractical for people to edit directly. + +The file `baserock.owl` is an initial effort to describe the Baserock data +model independently of any syntax or representation. + +We use the W3C standard Web Ontology Language (OWL), combined with the much +simpler RDF Schema language. Together, this allows defining the vocabulary we +can use to define build, integration and deployment instructions. There are +various ways to represent OWL 'ontologies'; `baserock.owl` uses a +representation format named Turtle, which is designed to be convenient for +hand-editing. + +The current data model is very closely tied to the current syntax, but we are +looking to change this and make it much more generic. This will involve +removing the current 'Chunk', 'Stratum', 'System' and 'Cluster' classes, and +adding something like 'thing with build instructions' and 'thing that contains +other things' instead. Name suggestions are welcome :-) + +It's useful to consider existing OWL and RDF Schema vocabularies that are +related to the Baserock data model. In future we can link the Baserock +reference system definitions with related data published elsewhere on the Web. +Here is an incomplete list: + + - Description of a Project (DOAP): https://github.com/edumbill/doap + - Software Ontology: https://robertdavidstevens.wordpress.com/2014/06/19/the-software-ontology-swo/ + - Software Packet Data Exchange (SPDX): https://spdx.org/about-spdx/what-is-spdx + + +Tools for working with the Baserock data model schema +----------------------------------------------------- + +It's difficult to find to a short, relevant 'getting started' guide. The +website http://www.linkeddata.org/ has a lot of background that should be +useful. + +The `rapper` commandline tool, which comes as part of the 'raptor2' C library, +is helpful for converting from one syntax to another, and checking if +`baserock.owl` is valid Turtle syntax. The 'raptor2' homepage is +. + +To check the syntax of `baserock.owl` using `rapper`: + + rapper -i turtle schemas/baserock.owl + + +Omissions / TODO items +---------------------- + +- Device nodes: chunk .morph files can list a set of device nodes. In + `chunk.json-schema` this is recognised, but in `baserock.owl` it is missing. + +- 'Lorry' mirroring instructions. These contain information on where 'upstream' + source code is kept, which should be considered part of the data model. A + JSON schema may be better off in lorry.git or + baserock/local-config/lorries.git. + +- Metadata in built systems. This is currently not standardised at all. + + +Comments +-------- + +As far as I know, Baserock is the first project to treat build, integration and +deployment instructions as data rather than code. If you have questions about +the schemas, the definitions format, or the overall approach, and they aren't +answered here or in , then please ask on +the baserock-dev@baserock.org mailing list. diff --git a/schemas/baserock.owl b/schemas/baserock.owl new file mode 100644 index 0000000..33113d8 --- /dev/null +++ b/schemas/baserock.owl @@ -0,0 +1,295 @@ +# Copyright (C) 2015 Codethink Limited +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation; version 2 of the License. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program. If not, see . + + +# This schema describes the Baserock data model. It describes how the data +# can be represented in computer memory, it doesn't specify anything about +# how it should be stored on disk or transferred. +# +# Please see README.schemas, and http://wiki.baserock.org/definitions/current/ +# for more information. +# +# This is not a brilliant schema, in Linked Data terms, because it's using +# Baserock-specific terminology and a rigid layout, instead of being a generic +# vocabulary for describing how to assemble software. However, it maps closely +# to the format that the existing Baserock reference system definitions use. +# We hope to produce a simpler and more flexible 2.x version of this schema in +# future. + + +# Partial OWL and RDF Schema glossary: +# +# domain: the set of objects that a can have a property. +# range: the set of possible values for a property. +# +# ObjectProperty: +# a property whose value must be another resource. +# DatatypeProperty: +# a property whose value is one of the datatype defined by XML Schema ("xsd") +# FunctionalProperty: +# a property which can only have one value per resource +# InverseFunctionalProperty: +# a property which can only have one resource per value + + +# Metadata + +@prefix : . +@prefix owl: . +@prefix rdfs: . +@prefix rdf: . +@prefix xsd: . +@prefix dc: . + +: a owl:Ontology ; + dc:title "Schema for Baserock data model" ; + dc:creator "The Baserock Project" ; + # Versioned according to Semantic Versioning http://www.semver.org/ + owl:versionInfo "0.9.0" . + + +## Entities + +# Source definitions + +:Morphology a owl:Class ; + rdfs:comment "A definition file." . + +:Cluster a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "Instructions for deploying one or systems." ; + owl:disjointWith :System, :Stratum, :Chunk . + +:System a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "A collection of strata in a form that can be executed." ; + owl:disjointWith :Cluster, :Stratum, :Chunk . + +:Stratum a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "A set of related chunks." ; + owl:disjointWith :Cluster, :System, :Chunk . + +:Chunk a owl:Class ; + rdfs:subClassOf :Morphology ; + rdfs:comment "An individual component, that can be built from a Git repository." ; + owl:disjointWith :Cluster, :System, :Stratum . + +# Container contents + +:SystemDeployment a owl:Class ; + rdfs:comment "Information for deploying one system of a cluster." . + +:ChunkReference a owl:Class ; + rdfs:comment "An instance of a chunk within a stratum." . + +# Products (for artifact split rules). + +:Artifact a owl:Class ; + rdfs:comment "One part of the result of building a morphology. The output of a build is split according to patterns, so there are multiple artifacts produced for a given source." . + +:StratumArtifact a owl:Class ; + rdfs:subClassOf :Artifact ; + rdfs:comment "Part of the result of building a stratum." ; + owl:disjointWith :ChunkArtifact. + +:ChunkArtifact a owl:Class ; + rdfs:subClassOf :Artifact ; + rdfs:comment "Part of the result of building a chunk." ; + owl:disjointWith :StratumArtifact. + + +## Shared properties + +# 'name' becomes part of the URL when we import definition .morph files as RDF, +# so it doesn't need a property. + +# Use dc:description for 'description', see: +# http://dublincore.org/documents/2012/06/14/dcmi-terms/?v=terms#terms-description + + +## Cluster-specific properties + +:containsSystemDeployment a owl:ObjectProperty ; + rdfs:domain :Cluster ; + rdfs:range :SystemDeployment ; + owl:minCardinality 1 . + + +## SystemDeployment-specific properties + +:deploysSystem a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range :System . + +:hasLabel a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string . + +:hasType a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "The .write extension used to perform the deployment." . + +:hasLocation a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "Deployment location. This is passed to the selected .write extension" . + +# FIXME: this is actually a key-value mapping, how do you do that in RDF properly? +:hasConfigurationSetting a owl:DatatypeProperty ; + rdfs:domain :SystemDeployment ; + rdfs:range xsd:string ; + rdfs:comment "Arbitrary key=value pair that is set in the environment of the .configure and .write extensions during deployment." . + + +## System-specific properties + +:containsStratumArtifact a owl:ObjectProperty ; + rdfs:domain :System ; + rdfs:range :StratumArtifact ; + owl:minCardinality 1 . + +# A build tool will only understand a certain set of architectures, but I think +# that should not be part of the data model. +:hasArchitecture a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :System ; + rdfs:range xsd:string . + +:hasConfigurationExtension a owl:DatatypeProperty ; + rdfs:domain :System ; + rdfs:range xsd:string ; + rdfs:comment "A .configure extension to be run when with system is deployed." . + + +## Stratum-specific properties + +:producesStratumArtifact a owl:ObjectProperty , rdf:Seq ; + rdfs:domain :Stratum ; + rdfs:range :StratumArtifact ; + rdfs:comment "iDescribes how this artifact is split once all chunks are built." . + +:hasStratumBuildDependency a owl:ObjectProperty ; + rdfs:domain :Stratum ; + rdfs:range :Stratum . + +:containsChunkReference a owl:ObjectProperty ; + rdfs:domain :Stratum ; + rdfs:range :ChunkReference ; + owl:minCardinality 1 . + + +## ChunkReference-specific properties + +:refersToChunk a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range :Chunk . + +:repo a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Git repo that this chunk's build instructions should be run in. Can be a keyed URL according to the repo-alias mapping, which isn't currently defined in this data model." . + +:ref a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Ref of the Git repo that should be checked out before building. Usually a SHA1." . + +:unpetrifyRef a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Name of the ref that should be checked out (useful when 'ref' is a SHA1 to keep track of the actual branch/tag name)." . + +:hasChunkBuildDependency a owl:ObjectProperty ; + rdfs:domain :ChunkReference ; + rdfs:range :Chunk . + +:prefix a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string ; + rdfs:comment "Value of the PREFIX environment variable in the build environment (defaults to /usr)" . + +# FIXME: it's possible to specify in OWL that 'bootstrap' and 'normal' are the +# only valid values. +:buildMode a owl:DatatypeProperty , owl:FunctionalProperty ; + rdfs:domain :ChunkReference ; + rdfs:range xsd:string . + + +## Chunk-specific properties + +# build-system isn't included here, as it overlaps with the *-commands +# fields in an unfortunate way. + +# Note that representing lists of things in RDF is a bit of a pain. +# http://smiy.sourceforge.net/olo/spec/orderedlistontology.html might +# be worth investigating. + +:producesChunkArtifact a owl:ObjectProperty , rdf:Seq ; + rdfs:domain :Chunk ; + rdfs:range :ChunkArtifact ; + rdfs:comment "Describes how this artifact is split once built." . + +:maxJobs a owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range xsd:integer ; + rdfs:comment "Number of parallel jobs that can be run for this chunk. Only useful if set to 1, to mark components which have Makefiles that do not work with `make -j N`.". + +:CommandSequence a owl:Class ; + rdfs:subClassOf rdf:Seq ; + rdfs:comment "An ordered sequence of commands." . + +:preConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:configureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postConfigureCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:preBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:buildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postBuildCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:preInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:installCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + +:postInstallCommands a owl:ObjectProperty , owl:FunctionalProperty ; + rdfs:domain :Chunk ; + rdfs:range :CommandSequence . + + +# Artifact properties + +:includes a owl:DatatypeProperty , rdf:Seq ; + rdfs:domain :Artifact ; + rdfs:range xsd:string ; + rdfs:comment "A regular expression pattern. The results of a build are matched against this pattern and any that match will be included in that artifact." . diff --git a/schemas/chunk.json-schema b/schemas/chunk.json-schema new file mode 100644 index 0000000..8de2fb5 --- /dev/null +++ b/schemas/chunk.json-schema @@ -0,0 +1,116 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema + +description: | + This is a JSON-Schema description of a 'chunk' .morph file, which is part of + the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # Corresponds to CommandSequence in Baserock data model. + command-sequence: + type: array + items: { type: string } + + # Corresponds to DeviceNode in Baserock data model. + device-node: + type: object + required: [type, filename, gid, uid, major, minor, permissions] + properties: + type: { type: string } + filename: { type: string } + gid: { type: integer } + uid: { type: integer } + major: { type: integer } + minor: { type: integer } + permissions: { type: string } + + # Defines one or more instances of ChunkArtifact from the Baserock data model. + split-rules: + type: array + items: + type: object + + required: [artifact, include] + additionalProperties: false + + properties: + artifact: {type: string} + include: + type: array + items: + type: string + format: regex + + system-integration-commands: + type: object + patternProperties: + # The property name here should correspond to the name of the chunk's + # artifacts, probably the '-bins' artifact if you are using the normal + # splitting rules. + ^.*$: + type: object + patternProperties: + ^.*$: + $ref: "#/definitions/command-sequence" + +# Corresponds to Chunk in Baserock data model. +type: object + +additionalProperties: false +required: [ 'name', 'kind'] + +properties: + name: { type: string } + kind: { enum: [ "chunk" ] } + + description: { type: string } + + build-system: { type: string } + max-jobs: { type: integer } + + products: + $ref: "#/definitions/split-rules" + + pre-configure-commands: + $ref: "#/definitions/command-sequence" + configure-commands: + $ref: "#/definitions/command-sequence" + post-configure-commands: + $ref: "#/definitions/command-sequence" + pre-build-commands: + $ref: "#/definitions/command-sequence" + build-commands: + $ref: "#/definitions/command-sequence" + post-build-commands: + $ref: "#/definitions/command-sequence" + pre-install-commands: + $ref: "#/definitions/command-sequence" + install-commands: + $ref: "#/definitions/command-sequence" + post-install-commands: + $ref: "#/definitions/command-sequence" + pre-strip-commands: + $ref: "#/definitions/command-sequence" + strip-commands: + $ref: "#/definitions/command-sequence" + post-strip-commands: + $ref: "#/definitions/command-sequence" + + system-integration: + $ref: "#/definitions/system-integration-commands" + + devices: + type: array + items: + $ref: "#/definitions/device-node" diff --git a/schemas/cluster.json-schema b/schemas/cluster.json-schema new file mode 100644 index 0000000..1a628c7 --- /dev/null +++ b/schemas/cluster.json-schema @@ -0,0 +1,64 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/cluster.json-schema + +description: + This is a JSON-Schema description of a 'cluster' .morph file, which is part + of the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # A reference to a System, plus one or more SystemDeployment for that system. + system-deployment-set: + type: object + + required: [ 'morph', 'deploy' ] + additionalProperties: false + + properties: + morph: { type: string } + deploy-defaults: + type: object + additionalProperties: true + deploy: + patternProperties: + ^.*$: { $ref: "#/definitions/system-deployment" } + subsystems: + type: array + items: { $ref: "#/definitions/system-deployment-set" } + + # Corresponds to SystemDeployment in Baserock data model. + system-deployment: + type: object + + required: [ 'type', 'location' ] + additionalProperties: true + + properties: + type: { type: string } + location: { type: string } + + +# Corresponds to Cluster in Baserock data model. +type: object + +#required: [ 'name', 'kind', 'systems' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "cluster" ] } + description: { type: string } + + systems: + type: array + items: { $ref: "#/definitions/system-deployment-set" } diff --git a/schemas/defaults.json-schema b/schemas/defaults.json-schema new file mode 100644 index 0000000..2f71342 --- /dev/null +++ b/schemas/defaults.json-schema @@ -0,0 +1,66 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/defaults.json-schema + +description: | + This is a JSON-Schema description of the DEFAULTS file specified in the + Baserock definitions format. DEFAULTS is a YAML file that contains global + defaults for a set of Baserock definitions. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions YAML serialisation format is the recommended way of + representing Baserock definitions on disk. The actual data model is described + separately. See for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + command-sequence: + type: array + items: {type: string} + + build-system: + type: object + additionalProperties: false + properties: + build-commands: {$ref: '#/definitions/command-sequence'} + configure-commands: {$ref: '#/definitions/command-sequence'} + install-commands: {$ref: '#/definitions/command-sequence'} + strip-commands: {$ref: '#/definitions/command-sequence'} + + split-rules: + type: array + items: + type: object + + required: [artifact, include] + additionalProperties: false + + properties: + artifact: {type: string} + include: + type: array + items: + type: string + format: regex + +type: object +additionalProperties: false + +properties: + # Predefined build systems. + build-systems: + type: object + patternProperties: + ^.*$: {$ref: '#/definitions/build-system'} + + # Predefined artifact splitting rules. + split-rules: + type: object + additionalProperties: false + properties: + chunk: {$ref: '#/definitions/split-rules'} + stratum: {$ref: '#/definitions/split-rules'} diff --git a/schemas/stratum.json-schema b/schemas/stratum.json-schema new file mode 100644 index 0000000..0330f37 --- /dev/null +++ b/schemas/stratum.json-schema @@ -0,0 +1,99 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema + +description: | + This is a JSON-Schema description of a 'stratum' .morph file, which is part + of the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # Defines one or more instances of StratumArtifact from the Baserock data + # model. + split-rules: + type: array + items: + type: object + + required: [artifact, include] + additionalProperties: false + + properties: + artifact: {type: string} + include: + type: array + items: + type: string + format: regex + + # Corresponds to ChunkReference in Baserock data model. + chunk-reference: + type: object + + required: [ 'repo', 'ref' ] + additionalProperties: false + + properties: + name: { type: string } + morph: { type: string } + repo: { type: string } + ref: { type: string } + unpetrify-ref: { type: string } + build-mode: { type: string } + prefix: { type: string } + build-system: { type: string } + build-depends: + type: array + items: { type: string } + artifacts: + type: object + # This defines which chunk artifacts go in which stratum artifact. + # E.g. "glibc-nss: build-essential-runtime" specifies the glibc-nss + # chunk artifact should go in the build-essential-runtime stratum + # artifact. + patternProperties: + ^.*$: { type: string } + + # This doesn't need any special treatment in the Baserock data model because + # it's a link to another stratum definition, without any extra info. + stratum-reference: + type: object + + required: [ 'morph' ] + additionalProperties: false + + properties: + morph: { type: string } + + +# Corresponds to Stratum in Baserock data model. +type: object + +required: [ 'name', 'kind', 'chunks' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "stratum" ] } + description: { type: string } + + build-depends: + type: array + items: + $ref: "#/definitions/stratum-reference" + + products: + $ref: "#/definitions/split-rules" + + chunks: + type: array + items: { $ref: "#/definitions/chunk-reference" } diff --git a/schemas/system.json-schema b/schemas/system.json-schema new file mode 100644 index 0000000..a2fc0c5 --- /dev/null +++ b/schemas/system.json-schema @@ -0,0 +1,59 @@ +$schema: http://json-schema.org/draft-04/schema# +id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/system.json-schema + +description: | + This is a JSON-Schema description of a 'system' .morph file, which is part of + the Baserock definitions YAML representation format. + + This JSON-Schema file is valid for VERSION 7 of the Baserock definitions + YAML serialisation format. + + The Baserock definitions format is the recommended way of representing + Baserock definitions on disk. The actual data model is described separately. + See https://wiki.baserock.org/definitions for more information. + + This schema is represented as YAML, so that it can be edited more easily. + You may need to convert to JSON if using a JSON-Schema tool that expects + its input to be an actual string containing data serialised as JSON. + +definitions: + # In the Baserock data model, this becomes a list of links to StratumArtifact + # entities. + stratum-reference: + type: object + + required: [ 'morph' ] + additionalProperties: false + + properties: + name: { type: string } + morph: { type: string } + artifacts: + type: array + items: { type: string } + + +# Corresponds to System in Baserock data model. +system: +type: object + +required: [ 'name', 'kind', 'strata' ] +additionalProperties: false + +properties: + name: { type: string } + kind: { enum: [ "system" ] } + description: { type: string } + + # Morph and YBD will only accept certain values for 'arch' based on + # hardcoded conditions in those tools. + arch: { type: string } + + strata: + type: array + items: + $ref: "#/definitions/stratum-reference" + + configuration-extensions: + type: array + items: { type: string } diff --git a/stratum.json-schema b/stratum.json-schema deleted file mode 100644 index 0330f37..0000000 --- a/stratum.json-schema +++ /dev/null @@ -1,99 +0,0 @@ -$schema: http://json-schema.org/draft-04/schema# -id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/chunk.json-schema - -description: | - This is a JSON-Schema description of a 'stratum' .morph file, which is part - of the Baserock definitions YAML representation format. - - This JSON-Schema file is valid for VERSION 7 of the Baserock definitions - YAML serialisation format. - - The Baserock definitions format is the recommended way of representing - Baserock definitions on disk. The actual data model is described separately. - See https://wiki.baserock.org/definitions for more information. - - This schema is represented as YAML, so that it can be edited more easily. - You may need to convert to JSON if using a JSON-Schema tool that expects - its input to be an actual string containing data serialised as JSON. - -definitions: - # Defines one or more instances of StratumArtifact from the Baserock data - # model. - split-rules: - type: array - items: - type: object - - required: [artifact, include] - additionalProperties: false - - properties: - artifact: {type: string} - include: - type: array - items: - type: string - format: regex - - # Corresponds to ChunkReference in Baserock data model. - chunk-reference: - type: object - - required: [ 'repo', 'ref' ] - additionalProperties: false - - properties: - name: { type: string } - morph: { type: string } - repo: { type: string } - ref: { type: string } - unpetrify-ref: { type: string } - build-mode: { type: string } - prefix: { type: string } - build-system: { type: string } - build-depends: - type: array - items: { type: string } - artifacts: - type: object - # This defines which chunk artifacts go in which stratum artifact. - # E.g. "glibc-nss: build-essential-runtime" specifies the glibc-nss - # chunk artifact should go in the build-essential-runtime stratum - # artifact. - patternProperties: - ^.*$: { type: string } - - # This doesn't need any special treatment in the Baserock data model because - # it's a link to another stratum definition, without any extra info. - stratum-reference: - type: object - - required: [ 'morph' ] - additionalProperties: false - - properties: - morph: { type: string } - - -# Corresponds to Stratum in Baserock data model. -type: object - -required: [ 'name', 'kind', 'chunks' ] -additionalProperties: false - -properties: - name: { type: string } - kind: { enum: [ "stratum" ] } - description: { type: string } - - build-depends: - type: array - items: - $ref: "#/definitions/stratum-reference" - - products: - $ref: "#/definitions/split-rules" - - chunks: - type: array - items: { $ref: "#/definitions/chunk-reference" } diff --git a/system.json-schema b/system.json-schema deleted file mode 100644 index a2fc0c5..0000000 --- a/system.json-schema +++ /dev/null @@ -1,59 +0,0 @@ -$schema: http://json-schema.org/draft-04/schema# -id: http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/schemas/system.json-schema - -description: | - This is a JSON-Schema description of a 'system' .morph file, which is part of - the Baserock definitions YAML representation format. - - This JSON-Schema file is valid for VERSION 7 of the Baserock definitions - YAML serialisation format. - - The Baserock definitions format is the recommended way of representing - Baserock definitions on disk. The actual data model is described separately. - See https://wiki.baserock.org/definitions for more information. - - This schema is represented as YAML, so that it can be edited more easily. - You may need to convert to JSON if using a JSON-Schema tool that expects - its input to be an actual string containing data serialised as JSON. - -definitions: - # In the Baserock data model, this becomes a list of links to StratumArtifact - # entities. - stratum-reference: - type: object - - required: [ 'morph' ] - additionalProperties: false - - properties: - name: { type: string } - morph: { type: string } - artifacts: - type: array - items: { type: string } - - -# Corresponds to System in Baserock data model. -system: -type: object - -required: [ 'name', 'kind', 'strata' ] -additionalProperties: false - -properties: - name: { type: string } - kind: { enum: [ "system" ] } - description: { type: string } - - # Morph and YBD will only accept certain values for 'arch' based on - # hardcoded conditions in those tools. - arch: { type: string } - - strata: - type: array - items: - $ref: "#/definitions/stratum-reference" - - configuration-extensions: - type: array - items: { type: string } -- cgit v1.2.1