summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorSam Thursfield <sam.thursfield@codethink.co.uk>2015-07-31 12:07:40 +0100
committerBaserock Gerrit <gerrit@baserock.org>2015-09-18 15:49:28 +0000
commit666c1f019c275a65fe96246a20e5bd3fbd73a8dd (patch)
tree16d164162a2b0abd5ed1493fec50e3ed3011ebd8
parentaeeab946dac9100be26756bfd4948f4b52df386e (diff)
downloaddefinitions-666c1f019c275a65fe96246a20e5bd3fbd73a8dd.tar.gz
Add schemas for Baserock definitions format
See schemas/README.schemas for information. Change-Id: I6c384692dbf70017a3ece2ed56c1f8cbe60b493d
-rw-r--r--README4
-rw-r--r--schemas/README.schemas137
-rw-r--r--schemas/baserock.owl295
-rw-r--r--schemas/chunk.json-schema116
-rw-r--r--schemas/cluster.json-schema64
-rw-r--r--schemas/stratum.json-schema99
-rw-r--r--schemas/system.json-schema59
-rwxr-xr-xscripts/yaml-jsonschema50
8 files changed, 822 insertions, 2 deletions
diff --git a/README b/README
index 887332d7..ed52d721 100644
--- a/README
+++ b/README
@@ -9,7 +9,8 @@ this repo and develop your own systems directly within it, or use it as a
reference point when developing your own set of definitions.
These definitions follow the Baserock definitions format, which is described at
-<http://wiki.baserock.org/definitions/>.
+<http://wiki.baserock.org/definitions/>, and also partly in the schemas/
+subdirectory.
The systems listed in the systems/ directory are example systems
that build and run at some point. The only ones we can be sure
@@ -17,7 +18,6 @@ that still build in current master of definitions are the ones that
we keep building in our ci system; they are listed in
http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/clusters/ci.morph
-
Keeping up to date
------------------
diff --git a/schemas/README.schemas b/schemas/README.schemas
new file mode 100644
index 00000000..a7789187
--- /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 <http://wiki.baserock.org/definitions/>.
+
+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 <http://www.yaml.org/>.
+
+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 <http://json-schema.org/>. 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 "<dump of entire file> 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
+<http://www.librdf.org/>.
+
+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 <http://wiki.baserock.org/definitions/>, 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 00000000..d699940c
--- /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 <http://www.gnu.org/licenses/>.
+
+
+# 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 : <http://baserock.org/definitions/example-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+@prefix dc: <http://purl.org/dc/elements/1.1/> .
+
+: 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 00000000..8de2fb5f
--- /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 00000000..1a628c7f
--- /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/stratum.json-schema b/schemas/stratum.json-schema
new file mode 100644
index 00000000..0330f37d
--- /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 00000000..a2fc0c5d
--- /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/scripts/yaml-jsonschema b/scripts/yaml-jsonschema
new file mode 100755
index 00000000..64f52a79
--- /dev/null
+++ b/scripts/yaml-jsonschema
@@ -0,0 +1,50 @@
+#!/usr/bin/env python
+# 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 <http://www.gnu.org/licenses/>.
+
+
+'''A tool to validate YAML files against the JSON-Schema schemas.
+
+This wraps Python `jsonschema` module so that YAML schemas can be understood
+and YAML data can be validated.
+
+Usage: yaml-jsonschema SCHEMA INPUT1 [INPUT2, ...]
+
+'''
+
+
+import jsonschema
+import yaml
+
+import sys
+
+
+schema_file = sys.argv[1]
+input_files = sys.argv[2:]
+
+
+with open(schema_file) as f:
+ schema = yaml.load(f)
+
+
+for input_file in input_files:
+ with open(input_file) as f:
+ data = yaml.load(f)
+
+ try:
+ jsonschema.validate(data, schema)
+ print("%s: valid" % input_file)
+ except jsonschema.ValidationError as e:
+ # Print 'e' instead of 'e.message' for more information!
+ print("%s: %s" % (input_file, e.message))