Finding

PartDraftv1.0.0-rc.2

Something a check, an agent or a person found about a record: a problem, a risk or a note. Traces, conformance checks and report imports all report findings.

https://opendevelopmentstandards.org/schema/1.0.0-rc.2/core/Finding.json

Fields

id
textnot empty
The record's id: unique within the document.
levelRequired
One ofthe codes below
How serious the finding is.
info
Worth knowing; needs no action.
warning
Needs a look.
error
Wrong; needs a fix.
codeRequired
Codesnake_case
A stable code that names what was found, so that findings can be counted and filtered: lower snake_case, with dots between the parts.
messageRequired
text
What was found, in words a reader can act on.
data
object with any keys
Free-form detail, such as the values compared.
origin
One ofthe codes below
Who or what raised the finding.
check
An automatic rule.
model
A machine-learning model or an agent built on one.
person
A person.
status
One ofthe codes below
Where the finding stands. Leave it out when no one has looked at it.
open
Not dealt with yet.
accepted
Agreed; a fix is due or done.
dismissed
Not a problem.
statusBypersonal
Id ofStakeholder
Who set the status.
statusAt
date-time (RFC 3339)
When the status was set.
records
List ofId ofany record
The ids of the records that the finding rests on.

Examples

An id that another example defines opens that record.

Example 1

{
  "id": "f1",
  "level": "warning",
  "code": "receptor.height.default",
  "message": "The receptor height was not given; 1.5 m was used.",
  "status": "open",
  "origin": "check"
}

Show 1 more example

Example 2

{
  "level": "error",
  "code": "limit.exceeded",
  "message": "The night-time level exceeds the limit by 3 dB.",
  "data": {
    "level": 43,
    "limit": 40
  },
  "records": [
    "trace-1"
  ]
}

Changes and file

Changes

0.1.0 First version.

Schema file

Show the JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://opendevelopmentstandards.org/schema/1.0.0-rc.2/core/Finding.json",
  "title": "Finding",
  "description": "Something a check, an agent or a person found about a record: a problem, a risk or a note. Traces, conformance checks and report imports all report findings.",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "description": "The record's id: unique within the document."
    },
    "level": {
      "type": "string",
      "enum": [
        "info",
        "warning",
        "error"
      ],
      "x-ods-options": [
        {
          "value": "info",
          "title": "Info",
          "description": "Worth knowing; needs no action."
        },
        {
          "value": "warning",
          "title": "Warning",
          "description": "Needs a look."
        },
        {
          "value": "error",
          "title": "Error",
          "description": "Wrong; needs a fix."
        }
      ],
      "description": "How serious the finding is."
    },
    "code": {
      "type": "string",
      "description": "A stable code that names what was found, so that findings can be counted and filtered: lower snake_case, with dots between the parts.",
      "pattern": "^[a-z0-9]+(_[a-z0-9]+)*(\\.[a-z0-9]+(_[a-z0-9]+)*)*$"
    },
    "message": {
      "type": "string",
      "description": "What was found, in words a reader can act on."
    },
    "data": {
      "type": "object",
      "x-ods-open": true,
      "description": "Free-form detail, such as the values compared."
    },
    "origin": {
      "type": "string",
      "enum": [
        "check",
        "model",
        "person"
      ],
      "x-ods-options": [
        {
          "value": "check",
          "title": "Check",
          "description": "An automatic rule."
        },
        {
          "value": "model",
          "title": "Model",
          "description": "A machine-learning model or an agent built on one."
        },
        {
          "value": "person",
          "title": "Person",
          "description": "A person."
        }
      ],
      "description": "Who or what raised the finding."
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "accepted",
        "dismissed"
      ],
      "x-ods-options": [
        {
          "value": "open",
          "title": "Open",
          "description": "Not dealt with yet."
        },
        {
          "value": "accepted",
          "title": "Accepted",
          "description": "Agreed; a fix is due or done."
        },
        {
          "value": "dismissed",
          "title": "Dismissed",
          "description": "Not a problem."
        }
      ],
      "description": "Where the finding stands. Leave it out when no one has looked at it."
    },
    "statusBy": {
      "type": "string",
      "description": "Who set the status.",
      "x-ods-ref": "Stakeholder",
      "x-ods-personal": "personal"
    },
    "statusAt": {
      "type": "string",
      "format": "date-time",
      "description": "When the status was set."
    },
    "records": {
      "type": "array",
      "items": {
        "type": "string",
        "x-ods-ref": "*"
      },
      "description": "The ids of the records that the finding rests on."
    }
  },
  "required": [
    "level",
    "code",
    "message"
  ],
  "patternProperties": {
    "^x-": {}
  },
  "unevaluatedProperties": false,
  "examples": [
    {
      "id": "f1",
      "level": "warning",
      "code": "receptor.height.default",
      "message": "The receptor height was not given; 1.5 m was used.",
      "status": "open",
      "origin": "check"
    },
    {
      "level": "error",
      "code": "limit.exceeded",
      "message": "The night-time level exceeds the limit by 3 dB.",
      "data": {
        "level": 43,
        "limit": 40
      },
      "records": [
        "trace-1"
      ]
    }
  ],
  "x-ods-status": "draft",
  "x-ods-kind": "part",
  "x-ods-module": "core",
  "x-ods-changes": {
    "0.1.0": "First version."
  }
}