Draft feature schema
ber_feature_model.yaml defines Dataset, ContigCollection,
Contig, and SequenceFeature. It imports the standalone attribute module, which defines
generic key/value pairs for metadata and evidence as well as GFF tags. See
the attribute contract. The schema remains a draft, not a
complete GFF3 interchange standard.
SequenceFeature was called Feature before version 0.2.0. It was renamed because "feature" also means
an earth-science sampling feature in BRIDGE (https://github.com/doe-bridge/bridge-central-schema/pull/5).
Data files don't change: they use the slots features and feature_id, and the Parquet export still
writes features.parquet. Table names derived from the class name do change: the DuckDB table and the
flat profile's tables are now sequence_feature and sequence_feature_*.
Optional FeatureLocation and LocationPart objects retain ordered, uncertain or
circular locations. See the location contract and migration guide.
With a structured location, scalar feature bounds are its indexing envelope;
parts are authoritative for occupancy.
source_document.yaml separately defines a physical source
document and its ordered records. It imports the same generic attribute module for
scoped comment metadata, without depending on SequenceFeature or NMDC DataObject. See the
source-document parser contract and
reproducible example.
gff3_reserved_attributes.yaml is not a schema: it transcribes the
GFF3 spec's eleven reserved column 9 tags, written in this repository on 2026-09-18 with its source
in the header. tests/test_gff3_reserved_attributes.py checks that every uppercase gff3: tag the
schemas here map to is one of them.
Versioned source profiles compose these two contracts with preservation/mapping records. GFF3 and BED12 use the same Dataset and generic Attribute classes; the latter also uses ordinary parent/child features for ordered blocks. The surrounding conversion bundle is validated by its executable profile contract, not by treating Dataset alone as a complete lossless serialization.
Genomes, bins, and stable identifiers
A ContigCollection is a set of contigs that belong together: an isolate genome, a
metagenome-assembled genome (MAG) bin, or a whole assembly. Contig.member_of lists the
collections a contig belongs to, so a metagenome contig can name both its assembly and its bin.
Features reach their genome or bin through their contig
(issue 41). Only an isolate,
mag, sag or virus collection stands for one organism, so a "same organism" query filters on
collection_type; a metagenome collection is a whole community. The class maps
exactly to KBase CDM ContigCollection, and collection_type uses CDM's ContigCollectionType
values, read from kbase/cdm-schema at commit c1a59b9 on 2026-09-25.
SequenceFeature.stable_identifiers holds identifiers an authority keeps across releases, such as an
NCBI GeneID. feature_id stays the key within one Dataset, because GFF3 ID values are not
meant to be persistent (issue 44).
NMDC annotation files have no such identifier for their own genes: the IMG gene oid in their KO
and EC files names the reference gene a query was aligned to.
strict-lint-config.yaml is a lint configuration, not a data model. Its documented
exception is the four literal GFF3 strand symbols, which are preserved despite naming rules.
Validation
| Command | Coverage |
|---|---|
just verify |
Corpus index integrity and checksums |
just validate-schema |
All three schema modules against the LinkML metamodel |
just lint-schema |
LinkML's default lint rules |
just lint-schema-recommended |
Recommended lint, allowing only the four documented strand-name warnings |
just lint-schema-strict |
Additional audit; intentionally reports the strand-name exception |
just validate-example |
Open generated JSON Schema for the default example |
just validate-example-closed |
Closed shape plus Dataset semantic checks |
just validate-source-example |
Closed SourceDocument shape plus exact-source/projection integrity |
just conversion-check |
Reproducible source-byte and mapped-field preservation report, including expected refusals |
just test |
Both real examples, invalid mutations, database preservation, and query controls |
just check |
Corpus, schema, recommended lint, examples, regression tests, and conversion report; also run by CI |
just diagram |
Regenerate the Mermaid diagram |
just flat-profile-audit |
Audit scalar-table compatibility through SchemaView |
The closed validator requires an object at the document root, rejects unknown root
fields, and checks JSON Schema formats, including source_files URIs. An empty object
is a valid empty Dataset because both collections are optional;
absent or null collections are treated as empty. These cases have regression coverage.
The harmonized Dataset profile requires a contig reference, coordinate system, and positive
1-based inclusive endpoints on every SequenceFeature; phase, when supplied, is 0, 1, or 2.
scripts/validate_closed.py additionally enforces start ≤ end, unique IDs within each entity
collection, resolved references (including each member_of collection), no parent cycles, and compatible parent coordinate spaces.
Contig intervals cannot exceed a known contig length. Protein intervals need a contig-relative
CDS parent and cannot exceed a supplied translation. Missing translations are allowed; their
upper bounds cannot be checked. Multiple parents must each be compatible with the child.
These cross-record checks run for Dataset, not when validating an isolated SequenceFeature.
Plain linkml-validate and exported JSON Schema alone do not enforce them. The profile
supports explicit parts and known-length circular references; the original GFF
conversion profile still refuses circular input. It does not validate biological CDS phase correctness, ontology terms,
or all GFF3 grammar.
CI also downloads the pinned, unvendored prior-art GFF schema and asserts its published
19-admissible/13-rejected audit totals. Locally, set PINNED_GFF_SCHEMA to that downloaded
schema's path to include this test; otherwise it is explicitly skipped. The current draft
model's separate totals, 35 admissible of 51 class and slot pairs, are tested without network access.
ContigCollection, Contig and SequenceFeature all expose generated_by and source_files. These remain optional
for sources lacking workflow metadata, but every supplied example populates them.
generated_by replaces the earlier SequenceFeature-only predicted_by field. The
source manifest records IDs and checksums for cited
artifacts. Record-level source lists may include sidecars from a different workflow than
the record's producer; they are not field-level provenance.
DuckDB mapping and queries
BRIDGE's scalar-only prototype profile is not a requirement of this model. The loader uses
native LIST columns for parents, lineages, and source files, and LIST of STRUCT for attributes.
Structured locations use a JSON column, and references retain optional topology.
SequenceFeature.seqid has no foreign key: it names a Contig, or for protein coordinates the CDS they
are measured along (protein coordinates), and one column
cannot reference two tables, so the Dataset validator checks it. Contig.member_of is a LIST of collection IDs.
The Dataset validator checks each one against the Dataset's contig_collections before loading;
DuckDB itself has no constraint on it. The physical mapping is explicit Python/SQL;
it is not a general LinkML database generator.
just build-duckdb validates its supplied schema and Dataset before opening the output.
It replaces the three model tables in one transaction, so validation or insertion failure
preserves an existing database. DuckDB BIGINT columns impose a 64-bit storage limit beyond
LinkML's integer type. New databases are staged beside their destination and published
after success; insertion failures leave no output or staging directory. Publication
refuses to overwrite a destination created concurrently, including during validation.
The tests exercise that race, rollback, and fresh-path cleanup for an out-of-range value.
just query-duckdb selects CDS parents with multiple distinct Pfams. The default mixed-evidence
example correctly produces no matches. Build the real three-Pfam example
for a positive result. Query requirements also cover explicit
genomic and protein intervals and generic attribute lookup, informed by the BERIL census.
The Python overlap helper, like its CLI, requires integer endpoints and rejects booleans,
floats (including NaN and infinity), and strings before executing SQL.
The source-document reader preserves comments/directives and their justified scope.
It keeps feature columns lexical; converting them into harmonized Features remains
a separate step. The real Prodigal example includes sequence-specific # comments
between feature rows, in addition to document-level directives.
Generated databases and test scratch files live under gitignored local/. No database
binary is committed: the YAML examples and scripts are the reviewable, reproducible artifacts.
Translation tables and score types
Contig.translation_table records the assigned NCBI genetic code a contig's coding features were
translated with, and SequenceFeature.score_type says what kind of number score is: bit_score,
e_value, p_value or score, each mapped to an EDAM data term
(issue 46). Unset score_type means
no source states the meaning, and a schema rule rejects a score_type on a feature with no
score. In the worked example only the HMMER rows set it. nmdc-lakehouse
documents NMDC's HMMER column 6 as a bit score
(https://github.com/microbiomedata/nmdc-lakehouse/blob/main/docs/pfam_annotation_gff.md). On all
five vendored HMMER rows that also have full_sequence_bitscore, column 6 is lower, so it reads
as the per-domain bit score. The lastal, Prodigal, GeneMark and INFERNAL scores are left unset.
The converters fill both slots
(issue 72; rules in
docs/conversion-profiles.md). gff3-contig and
the IMG functional mapping set translation_table when every CDS on a contig names the same
assigned code in its translation_table attribute, and refuse a contig whose CDS rows disagree.
In the vendored NMDC structural annotation (nmdc_wfmgan-11-5xxrm214.2: 1,199 CDS on 1,045
contigs, checked 2026-09-28) no contig mixes tables: 1,035 contigs get 11, 5 get 4, 3 get 15 and
2 get 25. nmdc-pfam-protein sets score_type: bit_score on its HMMER rows, and no other profile
sets score_type. scripts/validate_closed.py rejects a contig whose translation_table
disagrees with the translation_table attribute of any contig-coordinate CDS on it.
gff3-contig fills Contig.length_bp from ##sequence-region only under the ncbi metadata
profile, and only from a single region starting at 1, since NCBI writes one whole-record region per
record (issue 46). For any other
producer it infers no length from a declared region.
Representative isoforms
SequenceFeature.is_representative says whether the source names a transcript as its gene's representative
isoform (issue 48). Phytozome marks it
with longest=1 on one mRNA per gene. It is not is_selected, which records which competing call a
pipeline kept for a locus. Unset means the source does not say, and false only means what the
source states, as Phytozome's longest=0 does. The Dataset validator refuses two representatives
under one parent, and a mark, true or false, on a feature with no parent or with a parent that has a parent of
its own, such as an exon under an mRNA.
GFF3 reserved tags
SequenceFeature.name, note, dbxref and ontology_term hold the GFF3 reserved tags Name, Note,
Dbxref and Ontology_term (issue 43).
gff3-contig fills them and keeps every occurrence in attributes too, as it already did for ID,
Parent and product, so a query can use either. Alias and Derives_from occur in no corpus
file and have no slots yet.
Mappings
The GFF3 columns and the reserved tags that have slots carry exact_mappings to GFF3 and, where
Biolink has the same slot, to Biolink (issue 43).
They were read from biolink-model 4.4.4 on 2026-09-28, which also supplies the gff3: prefix IRI.
start and end map to Biolink's one-based start_coordinate and end_coordinate, not its
interbase slots, and only closely to faldo's begin and end, which link a region to a position
object rather than to an integer. Biolink lists GFF3's Dbxref as narrower than its own xref, so dbxref
maps broadly to biolink:xref. attributes is only close to GFF3's column 9, because it holds that column's ordered key/value pairs
rather than its text. feature_id is only close to gff3:ID, because it can be
synthetic or method-qualified, and SequenceFeature is only close to SO:0000110, sequence_feature, because
a SequenceFeature can also be a joined location or a protein-coordinate hit.
Alignment targets
SequenceFeature.target says where a hit aligns on the thing it matched, in that thing's own positions:
target_id, target_start, target_end, and optionally target_strand and a GFF3-style gap
(issue 94). The hit's own seqid,
start and end stay the query side. nmdc-pfam-protein fills it from HMMER's model_start and
model_end, with the Pfam accession as target_id. GFF3's Target tag occurs in no corpus file,
so gff3-contig doesn't parse it yet. The IMG per-method and NMDC lakehouse KO hits carry
subject_start and subject_end and can fill it in their own mappings.