Skip to content

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.