add package schema and documentation

docs/reference/index.md

@@ -1,25 +1,26 @@
 # Schema reference
 
+The Open Contracting for Infrastructure Data Standard (OC4IDS) provides a common approach for the disclosure of structured data on infrastructure projects and their related contracting processes.
+
+OC4IDS is comprised of a schema file and codelist files, and reference documentation is available for the [schema](reference.md) and [codelists](codelists.md).
+
+The schema can be explored using the [schema browser](schema.md) and can be [downloaded here](../../../../project-schema.json). The schema is expressed using [JSON Schema, draft 4](https://tools.ietf.org/html/draft-zyp-json-schema-04).
+
+OC4IDS data must be published as part of a [project package](package.md), which serves as a container for data on multiple projects and adds important metadata about the data publication.
+
+The OC4IDS schema reuses many of the building blocks from the Open Contracting Data Standard; these are introduced in the [Getting Started section of the OCDS documentation](http://standard.open-contracting.org/latest/en/getting_started/).
+
 ```eval_rst
 .. toctree::
    :maxdepth: 1
    :glob:
 
    schema
    reference
+   package
 
 ```
 
-The Open Contracting for Infrastructure Data Standard is described using JSON Schema 0.4.
-
-The [schema file is available here](../../../../_static/project-level/project-schema.json) and can be explored using the [schema browser](schema.md).
-
-Full schema and codelist [reference documentation is also available](reference.md).
-
-A [blank example JSON file is available here](../../../_static/blank.json).
-
-The OC4IDS schema reuses many of the building blocks from the OCDS schema; these are introduced in the [Getting Started section of the OCDS documentation](http://standard.open-contracting.org/latest/en/getting_started/).
-
 ## Data validation
 
 OC4IDS uses a permissive schema. It does not enforce strong technical validation requirements on data, other than some structural rules and data type rules (dates, numbers and strings).

docs/reference/package.md

@@ -0,0 +1,9 @@
+## Packaging data
+
+OC4IDS data must be published as part of project package, which acts as a container for data on multiple projects and adds important metadata about the publication. The project package schema describes this container.
+
+You can view an interactive version of the project package schema below (requires JavaScript) or [download it here](../../../../project-package-schema.json).
+
+Click on schema elements to expand the tree, or use the '+' icon to expand all elements. Use { } to view the underlying schema for any section.
+
+<script src="../../_static/docson/widget.js" data-schema="../../_static/project-level/project-package-schema.json"></script>

schema/project-level/project-package-schema.json

@@ -0,0 +1,102 @@
+{
+  "id": "http://standard.open-contracting.org/infrastructure/beta/project-package-schema.json",
+  "$schema": "http://json-schema.org/draft-04/schema#",
+  "title": "Schema for an OC4IDS project package",
+  "description": "A package of OC4IDS projects. Note that all projects within a package must have a unique project identifier.",
+  "type": "object",
+  "required": [
+    "uri",
+    "publisher",
+    "publishedDate",
+    "projects",
+    "version"
+  ],
+  "properties": {
+    "uri": {
+      "title": "Package identifier",
+      "description": "The URI of this package that identifies it uniquely in the world. Recommended practice is to use a dereferenceable URI, where a persistent copy of this package is available.",
+      "type": "string",
+      "format": "uri"
+    },
+    "publishedDate": {
+      "title": "Published date",
+      "description": "The date that this package was published. If this package is generated 'on demand', this date should reflect the date of the last change to the underlying contents of the package.",
+      "type": "string",
+      "format": "date-time"
+    },
+    "version": {
+      "title": "OC4IDS schema version",
+      "description": "The version of the OC4IDS schema used in this package, expressed as major.minor. For example: 0.9",
+      "type": "string",
+      "pattern": "^(\\d+\\.)(\\d+)$"
+    },
+    "projects": {
+      "title": "Projects",
+      "description": "A list of projects included in this package, in OC4IDS format.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "http://standard.open-contracting.org/infrastructure/beta/project-schema.json"
+      },
+      "uniqueItems": true
+    },
+    "publisher": {
+      "title": "Publisher",
+      "description": "Information to uniquely identify the publisher of this package.",
+      "type": "object",
+      "properties": {
+        "name": {
+          "title": "Name",
+          "description": "The name of the organization or department responsible for publishing this data.",
+          "type": "string"
+        },
+        "scheme": {
+          "title": "Scheme",
+          "description": "The scheme that holds the unique identifiers used to identify the item being identified.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "uid": {
+          "title": "uid",
+          "description": "The unique ID for this entity under the given ID scheme.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "uri": {
+          "title": "URI",
+          "description": "A URI to identify the publisher.",
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "uri"
+        }
+      },
+      "required": [
+        "name"
+      ]
+    },
+    "license": {
+      "title": "License",
+      "description": "A link to the license that applies to the data in this package. A Public Domain Dedication or [Open Definition Conformant](http://opendefinition.org/licenses/) license is strongly recommended. The canonical URI of the license should be used. Documents linked from this file may be under other license conditions. ",
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "uri"
+    },
+    "publicationPolicy": {
+      "title": "Publication policy",
+      "description": "A link to a document describing the publisher's [publication policy](http://standard.open-contracting.org/latest/en/implementation/publication_policy/).",
+      "type": [
+        "string",
+        "null"
+      ],
+      "format": "uri"
+    }
+  }
+}

schema/project-level/project-schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-04/schema#",
-  "id": "https://github.com/open-contracting/infrastructure/blob/master/schema/schema.json",
+  "id": "http://standard.open-contracting.org/infrastructure/0__9__beta/project-schema.json",
   "title": "Open Contracting for Infrastructure Data Standard Schema",
   "description": "The Open Contracting fo Infrastructure Data Standard Schema sets out a data structure for capturing and exchanging information about infrastructure projects in line with the disclosure requirements of the [CoST Infrastructure Data Standard](http://infrastructuretransparency.org/resource/977/).",
   "type": "object",