Source Fields (Layer A)

A Source is the core unit of Layer A — one knowledge source. Every UKS packet has at least one. This page documents every field, exactly as defined in the normative schema.

Required fields

Field	Type	Notes
id	string	Packet-scoped identifier (any stable string; UUID v4 recommended)
title	string (non-empty)	The source's title
source_type	enum (extensible)	See Source types
credibility_score	number 1–10	Curator's credibility assessment
evidence_grade	enum	See Evidence grading
clinical_status	enum	Never a boolean — see Evidence grading

Optional fields

Field	Type	Notes
url	string (uri)	Canonical URL
source_domain	enum (extensible)	See Source domains
api_source	string	API/database that returned it (e.g. pubmed, openalex)
summary	string	Short summary
key_findings	string[]	Each ≤ 500 chars
tags	string[]	Free-form tags
note	string	User-authored annotation
authors	string[]
date_published	date	ISO 8601 date
doi · pmid · openalex_id	string	Stable external identifiers
license_label	string	SPDX id or plain label (e.g. CC BY 4.0) — never collapse with rights_url
rights_url	string (uri)	Link to the license/rights
domain_data	object	Domain-specific structured data from deep analysis (merge, never overwrite)
raw_data	object	Original API response, preserved verbatim
in_kb	boolean	Bookmarked to the knowledge base
accessed_at	datetime	When fetched
_extensions	object	Escape hatch — never fails validation

Source types

Extensible knowledge-classification vocabulary. A novel value must be x-/x_ prefixed so consumers treat it as unknown rather than rejecting the packet; a plain unknown value (a typo) is rejected.

research_paper · review_article · meta_analysis · clinical_trial ·
government_report · database_entry · book_chapter · preprint ·
news_article · blog_post · product_page · dataset · api_response ·
patent · standard · other

Source domains

Also extensible (x-/x_ for novel values):

government · geospatial · scientific · bibliographic · cultural_heritage ·
legal · finance · health · open_web · ml · sensors · audio · dsp ·
vst_plugin · general

Additive siblings (optional, backward-compatible)

These extend a source without ever collapsing grading:

• claims[] — claim-level granularity. Each Claim carries its own statement (required), evidence_grade, clinical_status, confidence (0–1), supports[]/refutes[] (ids), and temporal_validity.
• temporal_validity — a staleness window: valid_as_of, valid_until, review_due, supersedes[], superseded_by[].
• quality_dimensions — methodology scoring alongside (never replacing) the GRADE letter: risk_of_bias (low/moderate/high/unclear), directness, consistency, precision, sample_size, replication_status (replicated/partially_replicated/not_replicated/contradicted/unreplicated), conflict_of_interest, study_design, assessment_tool.

Data contracts (Layer A extension)

data_contracts[] formally define named data types in the packet. Each has id, name, and fields[] (FieldDefinition: name, type ∈ string/number/ boolean/array/object/date/datetime/enum/any, plus required, nullable, enum_values, format, example, constraints).

→ Next: Scrape Targets (Layer B) · Evidence Grading