Data Package Dictionary¶
All access surfaces return the same public contract from argus.schemas.data_package. The contract is strict: undeclared fields are rejected, facts must cite source evidence, and conflicting evidence must appear in structured data quality issues.
DataPackage Fields¶
Private-storage evidence retains an opaque evidence_lookup_id equal to
evidence_id when its object_storage_uri is excluded from public output.
This optional reference is omitted when absent and does not expose the storage
address or grant access to controlled source text. It lets clients validate a
public response without requiring private source locators.
| Field | Type | Source semantics | Time semantics | Quality and license semantics |
|---|---|---|---|---|
package_type |
DataPackageType |
Identifies the result family such as company_fact_snapshot, event_timeline, or license_audit_report. |
Not a timestamp. | Controls downstream schema expectations. |
package_version |
string | Version of the producer contract for this package. | Supports reproducible reads with code and schema versions. | Used by compatibility checks. |
generated_at |
aware datetime | Set by the service producing the package. | Generation time, distinct from filing, known, revision, and invocation times. | Helps reproduce stale or regenerated output. |
effective_as_of |
aware datetime | UTC point used for the query. | Defaults to invocation time when omitted; an explicit value reproduces a historical view. | Facts must not leak knowledge available after this point. |
freshness |
list of SourceFreshness |
Actual source/domain data age, ingestion lag, latency class, and latest successful synchronization. | Calculated from persisted source and synchronization times. | Daily and delayed data must never imply real-time availability. |
request_subject |
string | Company, ticker, evidence id, source id, or other machine subject. | Not a timestamp. | Does not grant permission by itself. |
caller_id |
string | Authenticated machine caller id. | Not a timestamp. | Used for permission, license, and audit scope. |
institution_id |
string | Institution boundary for the call. | Not a timestamp. | Used for tenant, permission, and license decisions. |
request_purpose |
string | Declared machine purpose. | Not a timestamp. | Checked by permission, license, and output policy. |
result_status |
enum | complete, partial, empty, or unavailable. |
Not a timestamp. | Empty and unavailable results never require placeholder facts. |
coverage_gaps |
list of strings | Data domains not covered by this result. | May describe an as-of coverage gap. | Required for partial results and one valid explanation for empty results. |
unavailable_reasons |
list of strings | No-data, synchronization, license, or source-failure reasons. | May be paired with retry timing. | Required for unavailable results. |
retryable |
boolean | Whether the same request may succeed later. | Governs retry_after and next_available_at. |
Does not weaken license or permission checks. |
next_cursor |
string or null | Opaque continuation token for bounded result sets such as IR material search. | Encodes the last stable (known_at, fragment_id) position; reuse it with the same filters and as-of time. A page with a cursor is partial, including a bounded page with no matching facts. |
Prevents controlled material hydration from requiring an unbounded scan without falsely declaring a terminal empty result. |
facts |
list of FactRecord |
Structured facts returned by the core service; may be empty. | Facts carry their own known-at and revision fields in v2. | Every returned fact must reference existing source evidence. |
sections |
list of StructuredSection |
Machine-readable fact groupings. | Not a timestamp. | Each section references fact ids present in the package; it is not a narrative summary field. |
source_evidence |
list of SourceEvidence |
Source documents, fragments, fields, or model traces supporting facts. | Contains filing and retrieval times for each evidence item. | Evidence confidence and credibility must be explicit. |
data_period |
TimeRange |
Period covered by the fact values. | Uses start and end, and validates end >= start. |
Separates occurrence period from filing and known times. |
filing_time |
aware datetime | Filing or publication time from the source. | Used to distinguish source publication from known-at availability. | Supports point-in-time filtering. |
known_time |
aware datetime | Earliest time the system treats the data as knowable. | Historical queries must not return data with known_time after the query as-of time. |
Prevents future-data leakage. |
revision_time |
aware datetime or null | Revision marker when facts changed after first availability. | Null means no revision is represented in this package. | Revision status must not overwrite earlier point-in-time views. |
invocation_time |
aware datetime | Time of the machine call. | Distinct from generation and known times. | Used for audit reconstruction. |
data_quality |
DataQuality |
Quality level and structured issues for the package. | Quality issues can reference timing conflicts. | Required before facts are consumed by agents. |
credibility_level |
CredibilityLevel |
Overall credibility of the package. | Not a timestamp. | Packages containing model-assisted facts cannot claim top-tier credibility. |
data_license |
DataLicense |
License policy applied to the package. | Not a timestamp. | Defines status, allowed uses, prohibited uses, redistribution, institutions, and restricted fields. |
source_license_scopes |
list of SourceLicenseScope |
Source policies retained when a package combines records from multiple licenses. | Not a timestamp. | Each scope binds one source license to the package fields derived from that source; all scopes are enforced in addition to data_license. |
allowed_uses |
list of strings | Uses permitted for this result. | Not a timestamp. | Must align with the applied data license. |
prohibited_uses |
list of strings | Uses blocked for this result. | Not a timestamp. | Downstream agents must preserve these restrictions. |
output_restrictions |
list of strings | Machine-readable handling restrictions. | Not a timestamp. | Examples include JSON-only output and source citation requirements. |
structured_output_flags |
map of booleans | Explicit machine-readable output boundary flags. | Not a timestamp. | Records neutral data-boundary properties. |
audit_id |
string | Write-ahead audit identifier for this call. | Links started and terminal audit records over time. | Required for reproduction and compliance review. |
output_policy_version |
string | Output policy version applied to the result. | Supports historical policy reconstruction. | Required to prove prohibited content was filtered or rejected. |
FactRecord Fields¶
Filing results retain the source license snapshot recorded at ingestion. Each
fact's license_ref resolves to its actual source_license_scopes; a multi-source
summary intersects allowed uses and preserves every source restriction. Changing
request_purpose never adds a permitted use. Historical rows without captured
use terms become partial with filing_source_license_scope only when the server
license switch is explicitly enabled. With the default disabled switch, license
metadata alone does not downgrade the business result. Their
data_license.allowed_uses is empty and aggregate status is unknown.
The existing required, non-empty package summary lists remain compatible:
source_license_verification_required in allowed_uses is a metadata marker
that grants no use, and none_declared in prohibited_uses states that no
prohibition was recorded. Exact terms are in data_license and the source
scopes. structured_output_flags.source_license_use_scope_verified and
source_license_prohibitions_declared distinguish those cases. Neither marker
proves current subscription rights or changes license enforcement settings.
distribution_license_enforcement_enabled reports the actual server switch.
| Field | Meaning |
|---|---|
fact_id |
Stable identifier for the fact within the package. |
fact_type |
Neutral category such as identity, financial metric, event, quality, license, or audit. |
field_name |
Machine field name used by downstream tools. |
value |
Scalar fact value. |
evidence_ids |
Non-empty list of source evidence ids present in the same package. |
credibility_level |
Credibility assigned to this fact. |
extraction_method |
Structured source, rule based, model assisted, or caller submitted. |
confidence |
Required for model-assisted facts. |
review_status |
Required for model-assisted facts and used for human review workflow status. |
subject_id, security_id |
Stable company/subject identity and optional security identity. |
field_id, source_field_name, taxonomy |
Canonical field identity plus the exact source taxonomy field. |
value_type, value_decimal, value_lexical |
Lossless typed value representation; JSON floating point is never the only authority for a financial decimal. |
unit, currency, scale, precision |
Numeric and XBRL measurement semantics. |
period_type, period_start, period_end, fiscal_year, fiscal_period |
Financial period semantics. |
dimensions |
Non-prose source context and dimensional qualifiers. Controlled publisher titles, summaries, bodies, images, excerpts, credentials, storage locations, and restricted identifiers are forbidden. |
known_at, revision_time, status, supersedes_fact_id |
Bitemporal revision and withdrawal semantics. |
event_identity_status, matched_sec_provider_record_id |
Strongly typed distinction between SEC-confirmed events and unconfirmed discovery candidates, with an optional conservative SEC correlation. |
event_revision |
Strongly typed revision key, sequence, status, and superseded provider record. |
derived_event_feature |
Strongly typed descriptive sentiment/heat formula metadata; explicitly non-predictive and not a trading signal. |
license_ref, source_version_ref |
Applied license and immutable source version references. |
SourceEvidence Fields¶
| Field | Meaning |
|---|---|
evidence_id |
Unique evidence identifier within the package. |
source_type |
Regulatory filing, company announcement, authorized vendor, system-collected, internal system, caller-submitted, or model trace. |
source_file_id |
Source document or file identifier. |
provider_id |
Immutable internal provider identity used for source-governance enforcement; excluded from public serialization. |
document_url |
Link to a source document when allowed. |
evidence_lookup_id |
Optional opaque reference equal to evidence_id; preserves a valid public locator when private storage is excluded. Omitted when absent. |
object_storage_uri |
Internal-only object storage location; excluded from public serialization and generated public schemas. |
excerpt |
Controlled source excerpt retained internally and excluded from public serialization. |
fragment_position |
Character, byte, section, or parser-specific fragment position. |
page_number |
One-based page number when available. |
paragraph_position |
Paragraph or section position when no page number is available. |
field_path |
Parser or schema path for the field. |
filing_time |
Source filing or publication time. |
retrieved_at |
Time the system retrieved or parsed the evidence. |
parser_version |
Parser version that produced the evidence. |
evidence_confidence |
Numeric confidence from 0.0 to 1.0. |
credibility_level |
Credibility for the evidence. |
pointer_type |
Source document, source fragment, source field, or model trace. |
label |
Internal evidence label excluded from public serialization. |
is_conflicting |
Marks evidence that conflicts with another source. |
conflict_group_id |
Required when is_conflicting is true. |
conflict_reason |
Required when is_conflicting is true. |
content_trust |
External text defaults to untrusted_source_text; quoted source data is never an instruction. |
mime_type |
Source object media type used by the normalization boundary. |
source_object_sha256 |
Immutable source-object hash when the complete object is available. |
excerpt_boundary |
Explicit marker that the excerpt is bounded source data. |
DataLicense Fields¶
| Field | Meaning |
|---|---|
license_id |
Versioned license policy id. |
source |
Data source identifier. |
status |
authorized, restricted, prohibited, or unknown. |
allowed_uses |
Machine uses allowed by the license. |
prohibited_uses |
Machine uses denied by the license. |
redistribution |
Redistribution status. |
authorized_institutions |
Institutions allowed to use the data. |
restricted_fields |
Field names blocked or restricted by the license. |
SourceLicenseScope Fields¶
| Field | Meaning |
|---|---|
data_license |
Source-specific DataLicense resolved and enforced independently of the package aggregate license. |
field_names |
Non-empty list of package fields derived from that licensed source. |
DataQuality Fields¶
| Field | Meaning |
|---|---|
quality_level |
High, medium, low, or requires review. |
issues |
Structured list of QualityIssue entries. |
requires_human_review |
True when an agent should route the package to review before machine processing. |
coverage, completeness, freshness, consistency, source_agreement |
Optional normalized machine-readable quality dimensions. |
time_precision, evidence_specificity, parser_confidence, review_status |
Time, evidence, parser, and review quality metadata. |
QualityIssue Fields¶
| Field | Meaning |
|---|---|
issue_type |
Stable issue code such as source_evidence_conflict. |
severity |
Info, warning, or error. |
description |
Machine-readable explanation. |
field_name |
Optional affected field. |
evidence_ids |
Evidence ids related to the issue. |
Enumerations¶
For normalized external connector facts, SourceEvidence.source_file_id is
the captured connector record identifier and source_object_sha256 is the
SHA-256 of that stored source envelope, serialized as UTF-8 JSON with sorted
keys and compact separators. This identifies the captured source version; it
does not claim a byte-for-byte checksum of the provider's HTTP transport body.
The normalized business-content and license-scoped hashes are separate values.
Legacy facts without a verified raw record association have a normalized:
identifier and no raw checksum. They do not prove the original source version.
Evidence lookup validates source identity, hash association and capture time
without returning controlled source text or private storage locations.
| Enum | Values |
|---|---|
DataPackageType |
Includes company/security master, filing facts and evidence, events, market data, point-in-time datasets, catalogs, streams, and governance manifests. |
CredibilityLevel |
regulatory_original, company_official_announcement, authorized_vendor_data, system_collected_data, model_assisted_recognition, caller_submitted_unverified |
ExtractionMethod |
structured_source, rule_based, model_assisted, caller_submitted |
ReviewStatus |
not_required, pending_review, reviewed, rejected |
SourceType |
regulatory_filing, company_announcement, authorized_vendor, system_collected, internal_system, caller_submitted, model_trace |
LicenseStatus |
authorized, restricted, prohibited, unknown |
RedistributionStatus |
allowed, restricted, prohibited, unknown |
DataQualityLevel |
high, medium, low, requires_review |
QualityIssueSeverity |
info, warning, error |