For anyone adding a knowledge file · Protein rules are in the middle of this document

Rules for a knowledge record

A record in the ROMANN knowledge model has a kind, a home directory, and a sentence that says what does not belong on it. Write that sentence before you add the file. The checklist at the end is the save step.

Directories

schema/
├── entity_types/
├── process_types/
├── state_types/
├── property_types/
├── relation_types/
├── role_types/
├── context_types/
├── evidence_types/
├── units/
└── namespaces/

Each directory contains a template named example.<family>.v4.json. The template is not data. Copy the shape. Replace the id, the name, and the timeline keys. Delete placeholder names such as example_driver. Shipping a placeholder is a broken record, not a draft.

Instance files for molecules live under knowledge/entities/..., not under schema/. The schema file says what an entity type is. The knowledge file is one entity.

Kinds

Kind	Store this	Store it somewhere else
Entity	A thing with its own identity. For a protein, one continuous amino-acid sequence from N-terminus to C-terminus.	A gene used in place of the sequence. A concentration. A disease.
Process	Something that happens: catalysis, cleavage, folding.	The molecule that takes part. That molecule stays an entity.
State	A condition of an entity at a time, such as a conformation of the unmodified chain.	A phosphorylated form. That is a different record, a proteoform.
Relation	A typed link, in `relation_types/`, pointing at both ends.	A sentence inside the entity that mentions the other thing and hopes someone will notice.
Evidence	Source, method, and confidence for a claim.	The claim pasted into every entity that uses it.

Protein, as the test of the rules

A protein file is one chain, one sequence. Splice isoforms with different sequences are different proteins. A signal peptide still attached is a different sequence from the chain after it is cut. Two chains joined only by disulfides are not one sequence. Mature insulin’s A and B chains are two chains. The pair is a proteoform or a complex.

Stays on the protein	Does not stay on the protein
The sequence, the organism, the chain role (`precursor`, `mature_chain`, `subunit`).	A gene symbol standing in for the sequence.
Length, mass from residue masses, isoelectric point of the unmodified chain.	`k_cat`. A plasma concentration.
A conformational state of this unmodified chain.	A phosphorylated or glycosylated form.
An accession, named with its namespace. The accession does not replace the sequence when isoforms differ.	A disease association. An immunoassay result.

Ambiguous residues (X, B, Z) mean the sequence is incomplete. They do not mean a mixture of proteins.

Identity fields on an instance:

Field	Rule
`id`	`universe:protein:<slug>`. Changing it breaks every key that pointed here.
`name`	The protein name, including the isoform when the sequence differs.
`sequence`	One-letter amino acids, N to C. Alphabet declared. No DNA letters.
`length`	Derived from the sequence. Do not type a length that disagrees with it.
`organism`	A reference to an organism record.
`gene`	A reference. Nullable until that record exists. The sequence is still the identity.

The type file

A type file is not an instance. Minimum fields:

{
  "object_type": "entity_type",
  "id": "protein",
  "canonical_name": "Protein",
  "definition": "One continuous polypeptide chain, one sequence, N to C.",
  "family": "entity_types",
  "home": "schema/entity_types"
}

Field	Rule
`object_type`	Matches the directory. An entity type does not go in `relation_types/`.
`id`	Stable slug.
`definition`	One or two sentences that exclude the neighbor. If the sentence could describe both a gene and a protein, it is not finished.
`family` and `home`	Agree with the directory the file is saved in.

The v4 template also carries a measurement block: baseline, weights, hinges. Keep that block only if this type takes part in the timeline. If you keep it, replace every example_* key. Numbers in the template are not biological facts.

Evidence

A claim that a relation exists points at an evidence record. The evidence record names the source, the method, and a confidence. Copying the citation into the entity, the relation, and the process guarantees they will drift. One evidence record, referenced from the claim.

Checklist before you save

Name the kind: entity, process, state, relation, or evidence.
Write the sentence that says what is definitional and what is measured elsewhere. Put that sentence in definition or at the top of the instance note.
Confirm object_type, family, and home match the directory.
Point relations and evidence at their own files.
Search the file for example_. There should be no hits.
For a protein, confirm there is one sequence, no DNA letters, and no lab value.

If a tool wrote the file, a person still runs this checklist. The tool does not get to mark the record done.