endpoints for creating, deleting, fetching json schemas

POST /json_schema/:type/:name GET /json_schema/:id GET /json_schema/:type/:name/:version GET /json_schema/:type/:name/latest DELETE /json_schema/:id and /json_schema/:type/:name/:version (not /latest)
joyent · Jan 4, 2021 · 30c6d31 · 30c6d31
1 parent 8ce3c0d
commit 30c6d31
Show file tree

Hide file tree

Showing 18 changed files with 1,355 additions and 12 deletions.
diff --git a/docs/json-schema/request.json b/docs/json-schema/request.json
@@ -658,6 +658,64 @@
       },
       "type" : "object"
     },
+    "JSONSchema" : {
+      "allOf" : [
+        {
+          "$comment" : "Here we are essentially adding on to the main \"schema\" definition defined in the metaschema.",
+          "$id" : "/json_schema/request/JSONSchema_recurse",
+          "$recursiveAnchor" : true,
+          "$ref" : "https://json-schema.org/draft/2019-09/schema",
+          "properties" : {
+            "$anchor" : false,
+            "$dynamicAnchor" : false,
+            "$dynamicRef" : false,
+            "$id" : false,
+            "$recursiveAnchor" : false,
+            "$recursiveRef" : false,
+            "$schema" : {
+              "const" : "https://json-schema.org/draft/2019-09/schema"
+            },
+            "definitions" : false,
+            "dependencies" : false,
+            "format" : {
+              "$comment" : "iri-reference and uri-template are not supported by JSON::Schema::Draft201909",
+              "enum" : [
+                "date-time",
+                "date",
+                "time",
+                "duration",
+                "email",
+                "idn-email",
+                "hostname",
+                "idn-hostname",
+                "ipv4",
+                "ipv6",
+                "uri",
+                "uri-reference",
+                "iri",
+                "uuid",
+                "json-pointer",
+                "relative-json-pointer",
+                "regex"
+              ]
+            }
+          },
+          "unevaluatedProperties" : false
+        },
+        {
+          "$comment" : "Here we are adding on additional requirements for the top level schema only.",
+          "properties" : {
+            "description" : {
+              "$ref" : "common.json#/$defs/non_empty_string"
+            }
+          },
+          "required" : [
+            "description"
+          ],
+          "type" : "object"
+        }
+      ]
+    },
     "Login" : {
       "$ref" : "#/$defs/UserIdOrEmail",
       "default" : {

diff --git a/docs/json-schema/response.json b/docs/json-schema/response.json
@@ -1603,6 +1603,114 @@
       "type" : "array",
       "uniqueItems" : true
     },
+    "JSONSchema" : {
+      "$comment" : "this is the structure for responses from GET /json_schema/:type/:name/:version and GET /json_schema/:uuid, which fetches JSON Schemas from the database",
+      "allOf" : [
+        {
+          "$comment" : "Here we are essentially adding on to the main \"schema\" definition defined in the metaschema.",
+          "$id" : "response_JSONSchema_recurse",
+          "$recursiveAnchor" : true,
+          "$ref" : "https://json-schema.org/draft/2019-09/schema",
+          "properties" : {
+            "$schema" : {
+              "const" : "https://json-schema.org/draft/2019-09/schema"
+            },
+            "x-json_schema_id" : {
+              "$ref" : "common.json#/$defs/uuid"
+            }
+          },
+          "unevaluatedProperties" : false
+        },
+        {
+          "$comment" : "Here we are adding on additional requirements for the top level schema only.",
+          "properties" : {
+            "$comment" : {
+              "pattern" : "^created by ",
+              "type" : "string"
+            },
+            "$id" : {
+              "format" : "uri",
+              "minLength" : 1,
+              "type" : "string"
+            },
+            "description" : {
+              "$ref" : "common.json#/$defs/non_empty_string"
+            }
+          },
+          "required" : [
+            "$id",
+            "$schema",
+            "$comment",
+            "description",
+            "x-json_schema_id"
+          ],
+          "type" : "object"
+        }
+      ],
+      "contentMediaType" : "application/schema+json"
+    },
+    "JSONSchemaDescriptions" : {
+      "items" : {
+        "additionalProperties" : false,
+        "properties" : {
+          "$id" : {
+            "format" : "uri-reference",
+            "pattern" : "^/json_schema/",
+            "readOnly" : true,
+            "title" : "Canonical URI Identifier",
+            "type" : "string"
+          },
+          "created" : {
+            "format" : "date-time",
+            "readOnly" : true,
+            "title" : "Created",
+            "type" : "string"
+          },
+          "created_user" : {
+            "$ref" : "#/$defs/UserTerse",
+            "readOnly" : true,
+            "title" : "Created User"
+          },
+          "description" : {
+            "title" : "Description",
+            "type" : "string"
+          },
+          "id" : {
+            "$ref" : "common.json#/$defs/uuid",
+            "readOnly" : true,
+            "title" : "ID"
+          },
+          "name" : {
+            "$ref" : "common.json#/$defs/json_pointer_token",
+            "readOnly" : true,
+            "title" : "Name"
+          },
+          "type" : {
+            "$ref" : "common.json#/$defs/json_pointer_token",
+            "readOnly" : true,
+            "title" : "Type"
+          },
+          "version" : {
+            "$ref" : "common.json#/$defs/positive_integer",
+            "readOnly" : true,
+            "title" : "Version"
+          }
+        },
+        "required" : [
+          "id",
+          "$id",
+          "description",
+          "type",
+          "name",
+          "version",
+          "created",
+          "created_user"
+        ],
+        "type" : "object"
+      },
+      "type" : "array",
+      "uniqueItems" : true
+    },
     "JSONSchemaError" : {
       "$comment" : "very similar to https://json-schema.org/draft/2019-09/output/schema#/$defs/outputUnit - see https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10.4.2",
       "additionalProperties" : false,

diff --git a/docs/modules/Conch::Controller::JSONSchema.md b/docs/modules/Conch::Controller::JSONSchema.md
@@ -12,6 +12,41 @@ Get a query parameters, request, response, common or device\_report JSON Schema
 [query_params.json](../json-schema/query_params.json), [request.json](../json-schema/request.json), [response.json](../json-schema/response.json), [common.json](../json-schema/common.json), or [device_report.json](../json-schema/device_report.json),
 respectively). Bundles all the referenced definitions together in the returned body response.
 
+### create
+
+Stores a new JSON Schema in the database.
+
+The type names used in ["get\_from\_disk"](#get_from_disk) (`query_params`, `request`, `response`, `common`,
+`device_report`) cannot be used.
+
+The `$id`, `$anchor`, `definitions` and `dependencies` keywords are prohibited anywhere in the
+document. `description` is required at the top level of the document.
+
+### find\_json\_schema
+
+Chainable action that uses the `json_schema_id`, `json_schema_type`, `json_schema_name`, and
+`json_schema_version` values provided in the stash (usually via the request URL) to look up a
+JSON Schema, and stashes a simplified query (by `id`) to get to it in `json_schema_rs`, and
+the id itself in `json_schema_id`.
+
+### get\_single
+
+Gets a single JSON Schema specification document.
+
+### delete
+
+Deactivates the database entry for a single JSON Schema, rendering it unusable. This operation
+is not permitted until all references from other documents have been removed, with the
+exception of references using `.../latest` which will now resolve to a different document (and
+paths within that document will be re-verified).
+
+If this JSON Schema was the latest of its series (`/json_schema/foo/bar/latest`), then that
+`.../latest` link will now resolve to an earlier version in the series.
+
+### get\_metadata
+
+Gets meta information about all JSON Schemas in a particular type and name series.
+
 ## LICENSING
 
 Copyright Joyent, Inc.

diff --git a/docs/modules/Conch::DB::Result::JSONSchema.md b/docs/modules/Conch::DB::Result::JSONSchema.md
@@ -92,6 +92,25 @@ Type: belongs\_to
 
 Related object: [Conch::DB::Result::UserAccount](../modules/Conch%3A%3ADB%3A%3AResult%3A%3AUserAccount)
 
+## METHODS
+
+### TO\_JSON
+
+Include information about the JSON Schema's creation user, or user who added the JSON Schema to
+hardware (when fetched from a `hardware_product` context).
+
+### canonical\_path
+
+The canonical path to this resource.
+
+### schema\_document
+
+Returns the actual JSON Schema document itself, suitable for returning to a client or adding to
+a [JSON::Schema::Draft201909](https://metacpan.org/pod/JSON%3A%3ASchema%3A%3ADraft201909) object.
+
+Takes an optional coderef, which takes the result object and returns the value to be used for
+the `$id` property (otherwise, ["canonical\_path"](#canonical_path) will be used).
+
 ## LICENSING
 
 Copyright Joyent, Inc.

diff --git a/docs/modules/Conch::DB::ResultSet::JSONSchema.md b/docs/modules/Conch::DB::ResultSet::JSONSchema.md
@@ -0,0 +1,53 @@
+# Conch::DB::ResultSet::JSONSchema
+
+## SOURCE
+
+[https://github.com/joyent/conch-api/blob/master/lib/Conch/DB/ResultSet/JSONSchema.pm](https://github.com/joyent/conch-api/blob/master/lib/Conch/DB/ResultSet/JSONSchema.pm)
+
+## DESCRIPTION
+
+Interface to queries involving JSON schemas.
+
+## METHODS
+
+### type
+
+Chainable resultset that restricts the resultset to rows matching the specified `type`.
+
+### name
+
+Chainable resultset that restricts the resultset to rows matching the specified `name`.
+
+### version
+
+Chainable resultset that restricts the resultset to rows matching the specified `version`.
+
+### latest
+
+Chainable resultset that restricts the resultset to the single row with the latest version.
+(This won't make any sense when passed a resultset that queries for multiple types and/or
+names, so don't do that.)
+
+Does **NOT** take deactivated status into account.
+
+### with\_description
+
+Chainable resultset that adds the `json_schema` `description` to the results.
+
+### with\_created\_user
+
+Chainable resultset that adds columns `created_user.name` and `created_user.email` to the results.
+
+### resource
+
+Chainable resultset that restricts the resultset to the single row that matches
+the indicated resource.  (Does **not** fetch the indicated resource content -- you would need a
+`->column(...)` for that.)
+
+## LICENSING
+
+Copyright Joyent, Inc.
+
+This Source Code Form is subject to the terms of the Mozilla Public License,
+v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
+one at [https://www.mozilla.org/en-US/MPL/2.0/](https://www.mozilla.org/en-US/MPL/2.0/).
diff --git a/docs/modules/Conch::Route::JSONSchema.md b/docs/modules/Conch::Route::JSONSchema.md
@@ -10,6 +10,10 @@
 
 Sets up the routes for /json\_schema that do not require authentication.
 
+### secured\_routes
+
+Sets up the routes for /json\_schema that require authentication.
+
 ## ROUTE ENDPOINTS
 
 ### `GET /json_schema/query_params/:json_schema_name`
@@ -40,6 +44,54 @@ In the future, it will be modifiable; attempted modifications of this schema wil
 against all existing `hardware_product.specification` data, and any attempted modifications to
 specification data will be verified against this schema.
 
+### `POST /json_schema/:json_schema_type/:json_schema_name`
+
+Stores a new JSON Schema in the database. Unresolvable `$ref`s are not permitted.
+
+- Controller/Action: ["create" in Conch::Controller::JSONSchema](../modules/Conch%3A%3AController%3A%3AJSONSchema#create)
+- Request: [request.json#/$defs/JSONSchema](../json-schema/request.json#/$defs/JSONSchema) (Content-Type is expected to be
+`application/schema+json`).
+- Response: `201 Created`, plus Location header
+
+### `GET /json_schema/:json_schema_id`
+
+### `GET /json_schema/:json_schema_type/:json_schema_name/:json_schema_version`
+
+### `GET /json_schema/:json_schema_type/:json_schema_name/latest`
+
+Fetches the referenced JSON Schema document.
+
+- Controller/Action: ["get\_single" in Conch::Controller::JSONSchema](../modules/Conch%3A%3AController%3A%3AJSONSchema#get_single)
+- Response: [response.json#/$defs/JSONSchema](../json-schema/response.json#/$defs/JSONSchema) (Content-Type is `application/schema+json`).
+
+### `DELETE /json_schema/:json_schema_id`
+
+Deactivates the database entry for a single JSON Schema, rendering it unusable.
+This operation is not permitted until all references from other documents have been removed,
+exception of references using `.../latest` which will now resolve to a different document
+(and internal references will be re-verified).
+
+If this JSON Schema was the latest of its series (`/json_schema/foo/bar/latest`), then that
+`.../latest` link will now resolve to an earlier version in the series.
+
+- Requires system admin authorization, if not the user who uploaded the document
+- Controller/Action: ["delete" in Conch::Controller::JSONSchema](../modules/Conch%3A%3AController%3A%3AJSONSchema#delete)
+- Response: `204 No Content`
+
+### `GET /json_schema/:json_schema_type`
+
+Gets meta information about all JSON Schemas in a particular type series.
+
+- Controller/Action: ["get\_metadata" in Conch::Controller::JSONSchema](../modules/Conch%3A%3AController%3A%3AJSONSchema#get_metadata)
+- Response: [response.json#/$defs/JSONSchemaDescriptions](../json-schema/response.json#/$defs/JSONSchemaDescriptions)
+
+### `GET /json_schema/:json_schema_type/:json_schema_name`
+
+Gets meta information about all JSON Schemas in a particular type and name series.
+
+- Controller/Action: ["get\_metadata" in Conch::Controller::JSONSchema](../modules/Conch%3A%3AController%3A%3AJSONSchema#get_metadata)
+- Response: [response.json#/$defs/JSONSchemaDescriptions](../json-schema/response.json#/$defs/JSONSchemaDescriptions)
+
 ## LICENSING
 
 Copyright Joyent, Inc.

diff --git a/docs/modules/index.md b/docs/modules/index.md
@@ -79,6 +79,7 @@
 * [Conch::DB::ResultSet::Device](../modules/Conch::DB::ResultSet::Device)
 * [Conch::DB::ResultSet::DeviceNic](../modules/Conch::DB::ResultSet::DeviceNic)
 * [Conch::DB::ResultSet::DeviceReport](../modules/Conch::DB::ResultSet::DeviceReport)
+* [Conch::DB::ResultSet::JSONSchema](../modules/Conch::DB::ResultSet::JSONSchema)
 * [Conch::DB::ResultSet::Organization](../modules/Conch::DB::ResultSet::Organization)
 * [Conch::DB::ResultSet::Rack](../modules/Conch::DB::ResultSet::Rack)
 * [Conch::DB::ResultSet::RackLayout](../modules/Conch::DB::ResultSet::RackLayout)