Skip to main content

Category schema formats

Availability

GET /api/v1/categories/{code}/schema is GA on production (app.traceable.digital) as of v0.99.6.1. See Availability.

The schema endpoint returns the same field contract in four representations. The default (no format, or format=json) returns the structured JSON shown in Response examples. The three alternates below are for tooling, import, and human reading.

The examples use a representative 3-field sample. The live endpoint returns all fields for the category (for example 118 for BAT-STAT-001).

?format=json-schema​

Content-Type: application/json. A JSON Schema (draft-07) you can validate payloads against under any JSON Schema runtime (ajv, Python jsonschema, and so on). $id is urn:traceable:category:<code>:<version>, additionalProperties is false (unknown fields are invalid), and required[] lists the mandatory field_ids.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "urn:traceable:category:BAT-EV-001:3",
  "title": "BAT-EV-001 (v3)",
  "type": "object",
  "properties": {
    "nominal_voltage": {
      "type": "number",
      "title": "Nominal Voltage",
      "description": "Rated nominal voltage of the battery.",
      "minimum": 0,
      "maximum": 1000
    },
    "battery_status": {
      "type": "string",
      "title": "Battery Status",
      "enum": ["Original", "Repurposed", "Remanufactured"]
    },
    "manufacturing_site": {
      "type": "string",
      "title": "Manufacturing Site, City",
      "description": "Plant city, e.g. comma, quote test.",
      "pattern": "^[A-Za-z ]+$"
    }
  },
  "required": ["nominal_voltage"],
  "additionalProperties": false
}

Type mapping​

The Traceable field type maps to a JSON Schema type as follows:

Traceable typeJSON Schema type
integerinteger
float, number, calculated_metricnumber
booleanboolean
array_objectarray
groupobject
everything else (text, textarea, select, date, email, url, file, …)string

Per-property rules: title is the field label; description is help_text (omitted when null); enum is the field's options (when present); minimum and maximum come from validation.min and validation.max; pattern comes from validation.pattern. A select field becomes type: "string" with an enum.

?format=csv​

Content-Type: text/csv. One header row, then one row per field. Columns: field_id,label,type,required,ui_section,access_tier,options,help_text. Options are pipe-joined (A|B|C). Any value containing a comma, double quote, or newline is wrapped in double quotes with inner quotes doubled (RFC 4180 escaping), as manufacturing_site shows.

field_id,label,type,required,ui_section,access_tier,options,help_text
nominal_voltage,Nominal Voltage,float,true,Electrical,public,,Rated nominal voltage of the battery.
battery_status,Battery Status,select,false,General,public,Original|Repurposed|Remanufactured,
manufacturing_site,"Manufacturing Site, City",text,false,Provenance,poli,,"Plant city, e.g. comma, quote test."

The CSV reports the raw Traceable type (for example float, select), not the JSON Schema mapping.

?format=html​

Content-Type: text/html. A standalone HTML table, a quick human crib sheet. Required fields get <tr class="required">; field_id is wrapped in <code>; options are comma-joined; all values are HTML-escaped (&, <, >, "). The <h1> shows the field and required counts.

<!doctype html><html><head><meta charset="utf-8"><title>BAT-EV-001 field schema</title></head><body>
<h1>BAT-EV-001 (v3) — 3 fields, 1 required</h1>
<table border="1" cellpadding="4">
<thead><tr><th>field_id</th><th>label</th><th>type</th><th>required</th><th>access_tier</th><th>section</th><th>options</th><th>help</th></tr></thead>
<tbody>
<tr class="required">
  <td><code>nominal_voltage</code></td>
  <td>Nominal Voltage</td>
  <td>float</td>
  <td>yes</td>
  <td>public</td>
  <td>Electrical</td>
  <td></td>
  <td>Rated nominal voltage of the battery.</td>
</tr>
<tr>
  <td><code>battery_status</code></td>
  <td>Battery Status</td>
  <td>select</td>
  <td>no</td>
  <td>public</td>
  <td>General</td>
  <td>Original, Repurposed, Remanufactured</td>
  <td></td>
</tr>
<tr>
  <td><code>manufacturing_site</code></td>
  <td>Manufacturing Site, City</td>
  <td>text</td>
  <td>no</td>
  <td>poli</td>
  <td>Provenance</td>
  <td></td>
  <td>Plant city, e.g. comma, quote test.</td>
</tr>
</tbody></table></body></html>

Field notes​

  • access_tier (public, internal, poli, authority) is the effective tier: the most restrictive of the field's declared tier and any spec-driven (PoLI or authority) gate. Fields at poli or authority are restricted-visibility on the public DPP.
  • The default JSON format additionally carries unit and example (or unit_unspecified: true / example_unspecified: true when absent), plus field_count and required_count. The json-schema, csv, and html renderings are derived subsets for tooling, import, and human reading respectively.