dsh-standards 0.0.3 → 1.0.1

package/spec/schemas/attestation.schema.json

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PerryLink/dsh-standards/spec/schemas/attestation.schema.json",
+  "title": "DSH attestation",
+  "description": "A quality-grade attestation (A-E evidence, A-D grade) is orthogonal to the adoption levels. A attestation MUST NOT carry a level field.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "attestationId",
+    "subject",
+    "grade",
+    "claimLevel",
+    "status",
+    "issuedAt",
+    "expiresAt",
+    "scope",
+    "scheme",
+    "assessor",
+    "evidence",
+    "selfAssessed",
+    "disclaimer",
+    "verifyUrl"
+  ],
+  "not": {
+    "required": [
+      "level"
+    ]
+  },
+  "properties": {
+    "schema": {
+      "const": "dsh-attestation/1"
+    },
+    "attestationId": {
+      "type": "string",
+      "pattern": "^DSH-ATT-[0-9]{4}-[0-9]{3}$"
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repo",
+        "version"
+      ],
+      "properties": {
+        "repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$"
+        }
+      }
+    },
+    "grade": {
+      "enum": [
+        "A",
+        "B",
+        "C",
+        "D"
+      ]
+    },
+    "status": {
+      "enum": [
+        "draft",
+        "active",
+        "suspended",
+        "withdrawn",
+        "expired"
+      ]
+    },
+    "issuedAt": {
+      "type": "string",
+      "format": "date"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date"
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "dimensions",
+        "excluded"
+      ],
+      "properties": {
+        "dimensions": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "A",
+              "B",
+              "C",
+              "D",
+              "E"
+            ]
+          },
+          "uniqueItems": true
+        },
+        "excluded": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "platform": {
+          "type": "string"
+        },
+        "dsh": {
+          "type": "string"
+        },
+        "cordis": {
+          "type": "string"
+        }
+      }
+    },
+    "scheme": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "version"
+      ],
+      "properties": {
+        "id": {
+          "const": "dsh-certification"
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "assessor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "handle",
+        "role",
+        "coi"
+      ],
+      "properties": {
+        "handle": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "enum": [
+            "organizer",
+            "maintainer",
+            "reviewer",
+            "external-reviewer"
+          ]
+        },
+        "coi": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "result"
+        ],
+        "properties": {
+          "id": {
+            "enum": [
+              "A",
+              "B",
+              "C",
+              "D",
+              "E"
+            ]
+          },
+          "result": {
+            "enum": [
+              "PASS",
+              "FAIL",
+              "WARN",
+              "NOT-RUN"
+            ]
+          },
+          "url": {
+            "type": "string"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "note": {
+            "type": "string"
+          }
+        },
+        "anyOf": [
+          {
+            "required": [
+              "url"
+            ]
+          },
+          {
+            "required": [
+              "sha256"
+            ]
+          }
+        ]
+      }
+    },
+    "selfAssessed": {
+      "type": "boolean"
+    },
+    "disclaimer": {
+      "type": "string",
+      "minLength": 12
+    },
+    "notClaimed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "verifyUrl": {
+      "type": "string",
+      "pattern": "^https://"
+    },
+    "supersedes": {
+      "type": "string",
+      "pattern": "^DSH-ATT-[0-9]{4}-[0-9]{3}$"
+    },
+    "claimLevel": {
+      "enum": [
+        "self-reported",
+        "verified",
+        "peer-reviewed"
+      ],
+      "description": "self-reported when the assessor is the author; verified only with an independent reviewer; peer-reviewed with a panel."
+    },
+    "history": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "status",
+          "at"
+        ],
+        "properties": {
+          "status": {
+            "enum": [
+              "draft",
+              "active",
+              "suspended",
+              "withdrawn",
+              "expired"
+            ]
+          },
+          "at": {
+            "type": "string",
+            "format": "date"
+          },
+          "reason": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/spec/schemas/evidence.schema.json

@@ -0,0 +1,331 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PerryLink/dsh-standards/spec/schemas/evidence.schema.json",
+  "title": "DSH evidence record",
+  "description": "One record per subject-level-method run. The status enum is validated per level by the consumer: measured only for boost, manual only for flow.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "subject",
+    "level",
+    "status",
+    "scope",
+    "method",
+    "evidence",
+    "validity"
+  ],
+  "properties": {
+    "schema": {
+      "const": "dsh-levels/1"
+    },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "repo"
+      ],
+      "properties": {
+        "repo": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string"
+        },
+        "commit": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{7,40}$"
+        }
+      }
+    },
+    "level": {
+      "enum": [
+        "entry",
+        "flow",
+        "boost"
+      ]
+    },
+    "status": {
+      "enum": [
+        "recognized",
+        "static",
+        "runtime",
+        "blocked",
+        "failed",
+        "not-run",
+        "stale",
+        "manual",
+        "measured",
+        "not-measured",
+        "not-applicable",
+        "withdrawn"
+      ]
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "dsh",
+        "cordis"
+      ],
+      "properties": {
+        "dsh": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cordis": {
+          "type": "string",
+          "minLength": 1
+        },
+        "platform": {
+          "type": "string"
+        },
+        "pluginVersion": {
+          "type": "string"
+        }
+      }
+    },
+    "method": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tool",
+        "version"
+      ],
+      "properties": {
+        "tool": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "command": {
+          "type": "string"
+        },
+        "runId": {
+          "type": "string"
+        }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "result"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "result": {
+            "enum": [
+              "PASS",
+              "FAIL",
+              "WARN",
+              "NOT-RUN",
+              "BLOCKED",
+              "ERROR"
+            ]
+          },
+          "artifact": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          }
+        },
+        "anyOf": [
+          {
+            "required": [
+              "artifact"
+            ]
+          },
+          {
+            "required": [
+              "url"
+            ]
+          },
+          {
+            "required": [
+              "sha256"
+            ]
+          }
+        ]
+      }
+    },
+    "producer": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tool": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        },
+        "runId": {
+          "type": "string"
+        }
+      }
+    },
+    "validity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "generatedAt",
+        "expiresAt",
+        "rule"
+      ],
+      "properties": {
+        "generatedAt": {
+          "type": "string",
+          "format": "date"
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date"
+        },
+        "rule": {
+          "enum": [
+            "entry<=90d",
+            "flow<=180d",
+            "boost<=365d",
+            "certificate<=365d"
+          ]
+        }
+      }
+    },
+    "stale": {
+      "type": "boolean"
+    },
+    "notClaimed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "uniqueItems": true
+    },
+    "claimLevel": {
+      "enum": [
+        "observation",
+        "reference",
+        "advice"
+      ],
+      "description": "Sentence type, not strength. Market renders reference; developer renders advice."
+    },
+    "audience": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "official",
+          "market",
+          "developer"
+        ]
+      },
+      "uniqueItems": true
+    },
+    "render": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "template": {
+          "type": "string"
+        },
+        "recordHash": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "renderer": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "level": {
+            "const": "entry"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "status": {
+            "enum": [
+              "recognized",
+              "static",
+              "runtime",
+              "blocked",
+              "failed",
+              "not-run",
+              "stale",
+              "withdrawn",
+              "not-applicable"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "level": {
+            "const": "flow"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "status": {
+            "enum": [
+              "manual",
+              "runtime",
+              "failed",
+              "not-run",
+              "stale",
+              "withdrawn",
+              "not-applicable"
+            ]
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "level": {
+            "const": "boost"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "status": {
+            "enum": [
+              "measured",
+              "not-measured",
+              "failed",
+              "stale",
+              "withdrawn",
+              "not-applicable"
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/spec/schemas/report.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/PerryLink/dsh-standards/spec/schemas/report.schema.json",
+  "title": "DSH test report",
+  "description": "A test report (inspection) is not an attestation. It has no grade and no level. Attestation is a separate document that may cite a report ID.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "reportId", "subject", "method", "environment", "checks", "limitations", "issuedAt"],
+  "not": { "anyOf": [{ "required": ["grade"] }, { "required": ["level"] }] },
+  "properties": {
+    "schema": { "const": "dsh-report/1" },
+    "reportId": { "type": "string", "pattern": "^DSH-RPT-[0-9]{4}-[0-9]{3}$" },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["repo"],
+      "properties": {
+        "repo": { "type": "string" },
+        "version": { "type": "string" },
+        "commit": { "type": "string", "pattern": "^[0-9a-f]{7,40}$" }
+      }
+    },
+    "method": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool", "version"],
+      "properties": {
+        "tool": { "type": "string" },
+        "version": { "type": "string" },
+        "command": { "type": "string" },
+        "sample": { "type": "string" }
+      }
+    },
+    "environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["os", "node"],
+      "properties": {
+        "os": { "type": "string" },
+        "node": { "type": "string" },
+        "dsh": { "type": "string" },
+        "cordis": { "type": "string" }
+      }
+    },
+    "checks": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "result"],
+        "properties": {
+          "id": { "type": "string" },
+          "result": { "enum": ["PASS", "FAIL", "WARN", "NOT-RUN", "BLOCKED", "ERROR"] },
+          "reason": { "type": "string" },
+          "artifact": { "type": "string" }
+        }
+      }
+    },
+    "limitations": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+    "issuedAt": { "type": "string", "format": "date" },
+    "issuedBy": { "type": "string" }
+  }
+}