Files
paperspec/schemas/annotation.schema.json
T
alexmandClaude 3ab96d653f feat: structure and sequence annotation bodies; paperspec.structures and paperspec.sequences
Chemical structures (spec/18 section 18.6) and biological sequences (18.7) tied to
the words of a paper. Minor change: two new body kinds, optional properties and
seven rules, with no valid file made invalid.

- annotation schema: structure (SMILES or SMARTS, role, identity, written, label,
  accessions, force-field terms) and sequence (alphabet, role, identity, start,
  organism, regions, variants); body_kind in sql/store.sql; nine terms in the
  JSON-LD context; rules layer.structure.{value,identity,term} and
  layer.sequence.{value,identity,region,variant}.
- paperspec.structures reads the atoms and bonds of a SMILES or SMARTS with the
  standard library, so a term's atoms are checked without a toolkit; checked against
  RDKit on a corpus and random texts. paperspec.sequences checks alphabets,
  identities, regions and variants.
- fixtures/records/chemistry (on the main example) and biology (on the draft, which
  gains a last sentence), vectors/structures.jsonl and vectors/sequences.jsonl;
  check.py runs both layers and the vectors; counts, guides and CHANGELOG updated.
- the prose check no longer takes organism for a UK spelling.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B8cL4zN4XpaQF5cBtASzfq
2026-10-18 15:38:31 -04:00

1348 lines
35 KiB
JSON

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://paperspec.scient.ing/schemas/annotation.schema.json",
"title": "Annotation",
"description": "One line of annotations.jsonl in scienting-layer/1: a W3C Web Annotation; spec/18-layers.md.",
"$defs": {
"category": {
"description": "What a comment, caveat or question is about (spec/18 §18.4).",
"enum": [
"comment",
"context",
"critique",
"question",
"correction",
"feedback",
"resource"
]
},
"selector": {
"description": "A selector of a passage: the AnchorSelector, or the standard TextQuoteSelector that repeats the anchor's plain quote for tools that do not know ours (spec/18 §18.3).",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "AnchorSelector"
},
"anchor": {
"$ref": "anchor.schema.json"
}
},
"required": [
"type",
"anchor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextQuoteSelector"
},
"exact": {
"type": "string",
"minLength": 1
},
"prefix": {
"type": "string"
},
"suffix": {
"type": "string"
}
},
"required": [
"type",
"exact"
],
"additionalProperties": false
}
]
},
"accession": {
"description": "An entry of an outside database that a structure or a sequence is: `db` names the database in lower case (pubchem, chebi, cas, uniprot, genbank, refseq, ensembl, pdb) and `id` is the entry's identifier there (spec/18 §18.6).",
"type": "object",
"properties": {
"db": {
"type": "string",
"pattern": "^[a-z][a-z0-9-]*$",
"maxLength": 32
},
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"maxLength": 128
}
},
"required": [
"db",
"id"
],
"additionalProperties": false
},
"structureTerm": {
"description": "A bond, angle, torsion or improper that a paper gives values for, citing the structure's atoms by number (spec/18 §18.6).",
"type": "object",
"properties": {
"kind": {
"enum": [
"bond",
"angle",
"torsion",
"improper"
]
},
"atoms": {
"description": "Atom numbers, from 0 in the order the value writes its atoms. An improper lists its central atom first.",
"type": "array",
"items": {
"type": "integer",
"minimum": 0
},
"minItems": 2,
"maxItems": 4,
"uniqueItems": true
},
"types": {
"description": "The force field's atom types, one for each atom.",
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 16
},
"minItems": 2,
"maxItems": 4
},
"values": {
"description": "The parameters the paper gives, by the name it uses (k_r, r_eq, theta_0).",
"type": "object",
"additionalProperties": {
"$ref": "common.schema.json#/$defs/decimal"
},
"minProperties": 1
},
"units": {
"description": "The unit of each value, by the same names.",
"type": "object",
"additionalProperties": {
"type": "string",
"minLength": 1
}
},
"source": {
"description": "Where in the paper the values are given.",
"type": "string",
"minLength": 1
}
},
"required": [
"kind",
"atoms"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "bond"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 2,
"maxItems": 2
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "angle"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 3,
"maxItems": 3
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "torsion"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 4,
"maxItems": 4
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "improper"
}
},
"required": [
"kind"
]
},
"then": {
"properties": {
"atoms": {
"minItems": 4,
"maxItems": 4
}
}
}
}
]
},
"region": {
"description": "A stretch of a sequence, by residue number, both ends included (spec/18 §18.7).",
"type": "object",
"properties": {
"start": {
"type": "integer",
"minimum": 1
},
"end": {
"type": "integer",
"minimum": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
"variant": {
"description": "A substitution, stop or deletion at one residue: `ref` is the residue the value has there, `alt` what the variant has (`*` a stop, `-` a deletion) (spec/18 §18.7).",
"type": "object",
"properties": {
"position": {
"type": "integer",
"minimum": 1
},
"ref": {
"type": "string",
"pattern": "^[A-Z*]$"
},
"alt": {
"type": "string",
"pattern": "^[A-Z*-]$"
}
},
"required": [
"position",
"ref",
"alt"
],
"additionalProperties": false
}
},
"type": "object",
"properties": {
"@context": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 2
},
"id": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:annotation:[a-z0-9][a-z0-9._-]*/[a-hjkmnp-tv-z][0-9a-hjkmnp-tv-z]{6,25}$"
},
"type": {
"const": "Annotation"
},
"layer": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:layer:[a-z0-9][a-z0-9._-]*/[a-hjkmnp-tv-z][0-9a-hjkmnp-tv-z]{6,25}$"
},
"motivation": {
"enum": [
"commenting",
"describing",
"linking",
"questioning",
"assessing",
"tagging",
"classifying",
"identifying",
"editing",
"highlighting",
"bookmarking",
"replying",
"moderating"
]
},
"creator": {
"$ref": "common.schema.json#/$defs/agent"
},
"created": {
"$ref": "common.schema.json#/$defs/time"
},
"modified": {
"$ref": "common.schema.json#/$defs/time"
},
"body": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "gloss"
},
"audience": {
"enum": [
"novice",
"student",
"expert"
]
}
},
"required": [
"type",
"kind",
"value",
"audience"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"$ref": "common.schema.json#/$defs/claimRef"
},
"kind": {
"const": "claim-link"
},
"pin": {
"$ref": "common.schema.json#/$defs/claimPin"
},
"role": {
"enum": [
"states",
"uses",
"disputes"
]
}
},
"required": [
"type",
"kind",
"source",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"$ref": "common.schema.json#/$defs/claimRef"
},
"kind": {
"const": "symbol"
},
"pin": {
"$ref": "common.schema.json#/$defs/claimPin"
},
"key": {
"description": "The symbol's scienting-math/1 key, which the symbol claim's notation has too (spec/09 §9.4, spec/18 §18.4).",
"type": "string",
"minLength": 1
},
"symbol": {
"description": "The symbol as the span writes it.",
"type": "string",
"minLength": 1
}
},
"required": [
"type",
"kind",
"source",
"key"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "comment"
},
"category": {
"$ref": "#/$defs/category"
}
},
"required": [
"type",
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "caveat"
},
"category": {
"$ref": "#/$defs/category"
}
},
"required": [
"type",
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "question"
},
"for": {
"enum": [
"reader",
"group",
"authors"
]
},
"category": {
"$ref": "#/$defs/category"
}
},
"required": [
"type",
"kind",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "exercise"
},
"exercise": {
"$ref": "exercise.schema.json"
}
},
"required": [
"type",
"kind",
"value",
"exercise"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "citation-context"
},
"reference": {
"$ref": "common.schema.json#/$defs/nodeId"
},
"verdict": {
"enum": [
"supports",
"partly",
"does-not",
"cannot-tell"
]
},
"reason": {
"enum": [
"method",
"value",
"background",
"contrast",
"other"
]
}
},
"required": [
"type",
"kind",
"value",
"reference"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"minLength": 1
},
"kind": {
"const": "prerequisite"
}
},
"required": [
"type",
"kind",
"source"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"minLength": 1
},
"kind": {
"const": "crosslink"
},
"selector": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"const": "AnchorSelector"
},
"anchor": {
"$ref": "anchor.schema.json"
}
},
"required": [
"type",
"anchor"
],
"additionalProperties": false
},
"minItems": 1
}
},
"required": [
"type",
"kind",
"source",
"selector"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"kind": {
"const": "trace"
},
"source": {
"description": "The cited document, as a target's source names a document.",
"type": "string",
"pattern": "^tag:scient\\.ing,2026:doc:[a-z0-9][a-z0-9._-]*/[a-z][a-z0-9]*-[0-9a-hjkmnp-tv-z]{4,51}(\\.[a-z0-9][a-z0-9-]*)*$"
},
"selector": {
"description": "The passage of the cited document: an AnchorSelector, then a TextQuoteSelector when the anchor's quote is plain.",
"type": "array",
"items": {
"$ref": "#/$defs/selector"
},
"minItems": 1
},
"reference": {
"description": "The reference node of the citing document that the target's sentence cites and the trace is about.",
"$ref": "common.schema.json#/$defs/nodeId"
},
"note": {
"type": "string",
"minLength": 1
},
"verdict": {
"enum": [
"supports",
"partly",
"does-not",
"cannot-tell"
]
},
"proposer": {
"description": "The tool that proposed the trace, required when the annotation's creator is Software (spec/18 §18.4).",
"type": "object",
"properties": {
"model": {
"$ref": "common.schema.json#/$defs/model"
},
"run": {
"type": "string",
"minLength": 1
},
"score": {
"$ref": "common.schema.json#/$defs/decimal"
},
"rank": {
"type": "integer",
"minimum": 1
}
},
"required": [
"model",
"run"
],
"additionalProperties": false
}
},
"required": [
"type",
"kind",
"source",
"selector",
"reference"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"kind": {
"const": "structure"
},
"value": {
"description": "The structure as a SMILES or a SMARTS, whichever `format` says (spec/18 §18.6).",
"type": "string",
"minLength": 1,
"maxLength": 20000
},
"format": {
"enum": [
"chemical/x-daylight-smiles",
"chemical/x-daylight-smarts"
]
},
"role": {
"enum": [
"names",
"depicts",
"parametrizes",
"uses"
]
},
"identity": {
"description": "The InChIKey of a SMILES that has one; otherwise `smiles:` or `smarts:` and the first twelve hex digits of the SHA-256 of the value.",
"type": "string",
"pattern": "^([A-Z]{14}-[A-Z]{10}-[A-Z]|(smiles|smarts):[0-9a-f]{12})$"
},
"written": {
"description": "The structure as the paper writes it, when that is not SMILES or SMARTS: R-OH, CT-CT.",
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"accessions": {
"type": "array",
"items": {
"$ref": "#/$defs/accession"
},
"minItems": 1,
"uniqueItems": true
},
"terms": {
"type": "array",
"items": {
"$ref": "#/$defs/structureTerm"
},
"minItems": 1
}
},
"required": [
"type",
"kind",
"value",
"format",
"role",
"identity"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"kind": {
"const": "sequence"
},
"value": {
"description": "The residues in capital letters, a gap as `-` (spec/18 §18.7).",
"type": "string",
"minLength": 1,
"maxLength": 100000
},
"alphabet": {
"enum": [
"protein",
"dna",
"rna"
]
},
"role": {
"enum": [
"names",
"depicts",
"uses",
"reports"
]
},
"identity": {
"description": "The alphabet, a colon and the first sixteen hex digits of the SHA-256 of the residues with the gaps taken out.",
"type": "string",
"pattern": "^(protein|dna|rna):[0-9a-f]{16}$"
},
"start": {
"description": "The number of the first residue of the value in the molecule's own numbering; 1 when omitted.",
"type": "integer",
"minimum": 1
},
"label": {
"type": "string",
"minLength": 1
},
"organism": {
"type": "string",
"minLength": 1
},
"accessions": {
"type": "array",
"items": {
"$ref": "#/$defs/accession"
},
"minItems": 1,
"uniqueItems": true
},
"regions": {
"type": "array",
"items": {
"$ref": "#/$defs/region"
},
"minItems": 1
},
"variants": {
"type": "array",
"items": {
"$ref": "#/$defs/variant"
},
"minItems": 1
}
},
"required": [
"type",
"kind",
"value",
"alphabet",
"role",
"identity"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"alphabet": {
"const": "protein"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACDEFGHIKLMNPQRSTVWYBXZJUO*-]+$"
}
}
}
},
{
"if": {
"properties": {
"alphabet": {
"const": "dna"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACGTRYKMSWBDHVN-]+$"
}
}
}
},
{
"if": {
"properties": {
"alphabet": {
"const": "rna"
}
},
"required": [
"alphabet"
]
},
"then": {
"properties": {
"value": {
"pattern": "^[ACGURYKMSWBDHVN-]+$"
}
}
}
}
]
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "translation"
}
},
"required": [
"type",
"kind",
"value",
"language"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "description"
},
"role": {
"enum": [
"alt",
"long"
]
}
},
"required": [
"type",
"kind",
"value",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextualBody"
},
"value": {
"type": "string",
"minLength": 1
},
"format": {
"enum": [
"text/plain",
"text/markdown"
]
},
"language": {
"$ref": "common.schema.json#/$defs/language"
},
"kind": {
"const": "generated"
},
"generator": {
"type": "object",
"properties": {
"model": {
"$ref": "common.schema.json#/$defs/model"
},
"run": {
"type": "string",
"minLength": 1
}
},
"required": [
"model",
"run"
],
"additionalProperties": false
}
},
"required": [
"type",
"kind",
"value",
"generator"
],
"additionalProperties": false
}
]
},
"target": {
"oneOf": [
{
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:doc:[a-z0-9][a-z0-9._-]*/[a-z][a-z0-9]*-[0-9a-hjkmnp-tv-z]{4,51}(\\.[a-z0-9][a-z0-9-]*)*$"
},
"selector": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "AnchorSelector"
},
"anchor": {
"$ref": "anchor.schema.json"
}
},
"required": [
"type",
"anchor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextQuoteSelector"
},
"exact": {
"type": "string",
"minLength": 1
},
"prefix": {
"type": "string"
},
"suffix": {
"type": "string"
}
},
"required": [
"type",
"exact"
],
"additionalProperties": false
}
]
},
"minItems": 1
}
},
"required": [
"type",
"source",
"selector"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:annotation:[a-z0-9][a-z0-9._-]*/[a-hjkmnp-tv-z][0-9a-hjkmnp-tv-z]{6,25}$"
}
},
"required": [
"type",
"source"
],
"additionalProperties": false
}
]
},
{
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:doc:[a-z0-9][a-z0-9._-]*/[a-z][a-z0-9]*-[0-9a-hjkmnp-tv-z]{4,51}(\\.[a-z0-9][a-z0-9-]*)*$"
},
"selector": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"const": "AnchorSelector"
},
"anchor": {
"$ref": "anchor.schema.json"
}
},
"required": [
"type",
"anchor"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "TextQuoteSelector"
},
"exact": {
"type": "string",
"minLength": 1
},
"prefix": {
"type": "string"
},
"suffix": {
"type": "string"
}
},
"required": [
"type",
"exact"
],
"additionalProperties": false
}
]
},
"minItems": 1
}
},
"required": [
"type",
"source",
"selector"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"const": "SpecificResource"
},
"source": {
"type": "string",
"pattern": "^tag:scient\\.ing,2026:annotation:[a-z0-9][a-z0-9._-]*/[a-hjkmnp-tv-z][0-9a-hjkmnp-tv-z]{6,25}$"
}
},
"required": [
"type",
"source"
],
"additionalProperties": false
}
]
},
"minItems": 1
}
]
},
"status": {
"enum": [
"proposed",
"confirmed",
"rejected",
"withdrawn"
]
},
"receipt": {
"$ref": "common.schema.json#/$defs/recordId"
},
"rights_use": {
"type": "string",
"minLength": 1
}
},
"required": [
"@context",
"id",
"type",
"layer",
"motivation",
"creator",
"created",
"body",
"target",
"status"
],
"additionalProperties": false,
"allOf": [
{
"if": {
"properties": {
"status": {
"const": "confirmed"
}
}
},
"then": {
"required": [
"receipt"
]
}
},
{
"description": "A tool's trace names the tool and the run that proposed it (spec/18 §18.4).",
"if": {
"properties": {
"creator": {
"properties": {
"type": {
"const": "Software"
}
},
"required": [
"type"
]
},
"body": {
"properties": {
"kind": {
"const": "trace"
}
},
"required": [
"kind"
]
}
},
"required": [
"creator",
"body"
]
},
"then": {
"properties": {
"body": {
"required": [
"proposer"
]
}
}
}
}
]
}