Peptide Identity Ontology + Read API v0.1 — peptidoforms, provenance, and interoperable contracts

[hummbl-dev]

Parent coordination: https://github.com/hummbl-dev/hummbl-dev/issues/145
Claim schema dependency: hummbl-io/claim-evidence-ledger#8
Seed dataset dependency: hummbl-io/claim-evidence-ledger#9
Bibliography/source registry: https://github.com/hummbl-dev/hummbl-bibliography/issues/77

Status

CANDIDATE KNOWLEDGE-AS-CODE DOMAIN PACK — NON-CANONICAL — READ-ONLY API CONTRACT

Objective

Create a peptide-domain ontology and machine-readable contract that distinguishes sequence, peptidoform, physical preparation, assembly, and formulated product while interoperating with the existing HUMMBL Evidence Graph and public scientific standards.

The first phase is a schema/ontology/API contract, not a deployed database or service.

Identity invariant

same_residue_sequence_as does not imply same_peptidoform_as, same_preparation_as, or same_product_as.

The ontology must preserve modifications, stereochemistry, terminal states, crosslinks, topology, assemblies, batches, formulations, and uncertainty where material.

Required classes

Molecular identity

• PeptideEntity
• PeptideSequence
• Residue
• Bond
• Modification
• TerminalState
• Crosslink
• Topology
• Peptidoform
• Conformer
• Assembly

Biological origin

• Gene
• Transcript
• OpenReadingFrame
• Precursor
• ProcessingEvent
• Protease
• ModificationEnzyme
• BiosyntheticGeneCluster
• NRPSAssemblyLine
• Organism
• Tissue
• CellType
• Compartment

Function and mechanism

• Target
• BindingEvent
• Activity
• Pathway
• Phenotype
• Toxicity
• ImmuneRecognition
• MaterialProperty

Evidence and measurement

Reuse or map to the existing graph/ledger for:

• Claim
• Source
• EvidenceItem
• Assay
• Sample
• Preparation
• Observation
• Dataset
• Spectrum
• Structure
• Model
• Prediction
• ReplicationAttempt
• Conflict

Engineering and product

• SynthesisRoute
• ReactionStep
• PurificationStep
• Batch
• Impurity
• Formulation
• ContainerClosure
• StabilityStudy
• Product
• Indication
• RegulatoryDecision

Governance and provenance

• Agent
• Activity
• Review
• Decision
• Version
• Policy
• ValidationRule
• AccessControl
• AuditEvent

Required relations

At minimum define direction, domain/range, cardinality posture, and misuse notes for:

encoded_by
translated_from
cleaved_from
processed_by
modified_by
cyclized_by
contains_residue
has_sequence
has_modification
has_terminal_state
has_crosslink
has_topology
has_peptidoform
same_residue_sequence_as
same_stereochemical_sequence_as
same_peptidoform_as
different_peptidoform_from
binds
agonizes
antagonizes
inhibits
activates
is_substrate_of
presented_by
recognized_by
localizes_to
assembles_into
measured_by
observed_in
derived_from_sample
generated_spectrum
identified_as
quantified_as
supported_by
contradicted_by
failed_to_replicate
supersedes
qualified_by_context
synthesized_by
purified_by
contains_impurity
formulated_as
administered_by
authorized_for
was_generated_by
was_derived_from
was_attributed_to
was_reviewed_by
was_revision_of

Do not duplicate generic evidence/provenance relations if the Evidence Graph or W3C PROV mapping already supplies them.

Faceted classification

Represent independent facets rather than one forced tree:

• origin: ribosomal, precursor-processed, RiPP, proteolytic, nonribosomal, hybrid, recombinant, chemical, chemoenzymatic, in-silico candidate;
• topology: linear, cyclic, side-chain-cyclic, branched, multi-chain, disulfide-linked, lariat, knotted, stapled, other-crosslinked, assembled, conjugated;
• composition: canonical/noncanonical residues, D-residues, backbone substitutions, modifications, labels, payloads;
• function: signal, antigen, antimicrobial, toxin, inhibitor, targeting ligand, material, catalyst, diagnostic, therapeutic;
• evidence stage and status;
• biological and experimental context.

Standards and identifiers

Evaluate and map rather than reinvent:

• ProForma 2.0 for peptidoform notation;
• UniProt for protein/precursor identifiers;
• ChEBI for chemical entities;
• Unimod and PSI-MOD for modifications;
• HUPO-PSI formats/vocabularies for MS/proteomics;
• W3C PROV-O for provenance;
• DOI, PMID, ORCID, ROR, and identifiers.org patterns;
• JSON Schema for validation;
• JSON-LD/RDF for graph exchange;
• OpenAPI 3.1 for service contract.

Document gaps where these standards do not fully represent stereochemistry, ambiguous topology, preparations, formulations, or evidence state.

Minimum peptidoform record

peptidoform_id:
preferred_name:
sequence:
sequence_notation:
stereochemistry:
n_terminus:
c_terminus:
modifications:
crosslinks:
topology:
molecular_formula:
monoisotopic_mass:
average_mass:
charge_states:
counterions:
known_assemblies:
external_identifiers:
identity_evidence:
version:

Unknown fields must remain unknown; do not silently apply defaults that imply canonical L-amino acids, free termini, unmodified state, or monomeric identity.

Read-only API contract

Define but do not deploy endpoints such as:

GET /peptides/{peptide_id}
GET /peptidoforms/{peptidoform_id}
GET /preparations/{preparation_id}
GET /claims/{claim_id}
GET /claims?subject_id=&predicate=&status=&as_of=
GET /evidence?claim_id=
GET /conflicts?entity_id=
GET /sources/{source_id}
GET /assays/{assay_id}
GET /history/timeline?from=&to=&lineage=

Every response should expose version, evidence/provenance links, and unresolved identity state. The server URL must remain a placeholder unless a real deployment is separately authorized and verified.

Tests and fixtures

Create fixtures for:

• same sequence, different terminal state;
• same sequence, different stereochemistry;
• same sequence, different disulfide connectivity;
• linear versus cyclic topology;
• peptide–drug or peptide–radionuclide conjugate;
• multi-chain peptide/protein hormone;
• unresolved modification position;
• preparation containing multiple peptidoforms;
• product with same active sequence but different formulation;
• invalid same-sequence/same-peptidoform collapse;
• unresolved external identifier;
• provenance chain from source to extracted claim to reviewed record.

Acceptance criteria

• Ontology is documented and machine-parseable.
• Identity hierarchy prevents sequence-only equivalence errors.
• Facets are independent and composable.
• Claim/evidence and provenance classes reuse existing contracts where possible.
• Standards mappings include explicit gap analysis.
• ProForma examples parse or any unsupported constructs are documented.
• Valid fixtures pass and invalid fixtures fail for expected reasons.
• OpenAPI contract validates as OpenAPI 3.1.
• API is clearly marked candidate_not_deployed.
• Cross-repo IDs resolve for the seed records or remain explicitly unresolved.
• No new HUMMBL/BaseN canonical terminology is introduced.
• PR includes integration tests and independent ontology review.

Non-goals

• Deploying a graph database or production API.
• Replacing ChEBI, UniProt, ProForma, or HUPO-PSI.
• Modeling every chemical detail in v0.1.
• Automatically resolving ambiguous identities.
• Publishing therapeutic recommendations.

Receipt requirement

Record class/relation counts, standards mapped, gaps found, fixture matrix, API validation output, cross-repo compatibility findings, commit SHA, and reviewer disposition.

[hummbl-dev]

---

Automated triage run (2026-07-24)

• Category: feature
• Priority: P2
• Severity: medium
• Staleness: fresh
• Recommended next action: Define the peptidoform identity schema with provenance fields and implement the read API once claim-evidence-ledger dependencies (Governed Knowledge Projection Compiler v0.1 — candidate schema, invalidation, and receipts #8, Epic B: Source Adapter SDK — common interface, provenance hooks, and conformance fixtures #9) are resolved.

Notes: This is the knowledge-as-code entry point for the peptide science program, requiring interoperable contracts across claim-evidence-ledger and bibliography repos. The peptidoform provenance model is the core deliverable.