7lens Data Model — Conventions

Canonical copy

Copied from the 7lens app repository, docs/datamodel/7lens-data-model-conventions.md at 012d434, on 2026-11-11. Document version 1.0, dated 2026-10-30. The app repository is the source of truth. Do not edit this page here; change the source and re-run npm run sync:reference.

This is a strategic source document: how 7lens represents shared concepts. Where a shared concept is represented — time, a person, a quantity, a declaration — these rules apply.

---

Purpose

Three layers stay apart.

1. Customer preferences change presentation and derived-view aggregation only. A preference never rewrites a stored value, a YAML file, a backup, or an API or MCP payload.
2. Canonical conventions are how time, money, people, ids, quantities, lifecycle, and provenance are stored. They are a closed core, versioned with @7lens/contracts. Lenses, domains, and customers extend that core only through the one declaration language. An extension may narrow a declaration. It may not redefine a core concept or add a recognition key.
3. Attribute definitions say, for each attribute, its type, meaning, unit, vocabulary, constraints, and validation.

IANA time zones, ISO 4217, BCP 47, and UCUM are adopted directly. Their reference lists are pinned in @7lens/contracts. Provenance follows W3C PROV concepts and does not use PROV serialization. JSON Schema is an export format. It is not the authoring language.

This document defines nine categories:

1. Time
2. Naming
3. People and accountability
4. Provenance
5. Lifecycle
6. Quantities
7. Money
8. Attribute definitions
9. Customer preferences

Starter-pack contents are not rules. A number filled into a pack, including an availability target, is that pack’s data.

Identity rules here are opaque asset ids, snake_case for new references, and the separation of source-system keys from the 7lens id.

---

Concepts

Time

A timestamp (value type datetime) is RFC 3339 with a required offset. Any offset is accepted on input. 7lens writes UTC with a Z suffix and millisecond precision, and truncates finer precision. The raw source payload keeps the original text. A timestamp without an offset, a date-only value offered as a timestamp, and a leap second are rejected. A source that emits local times has its zone configured on that source and recorded in provenance.

A calendar date (value type date) is YYYY-MM-DD. It has no time and no zone. It is never converted to a timestamp for display. Configuration definitions use dates. Inventory facts, events, and history use timestamps.

A duration (value type duration) follows the RFC 3339 duration grammar. Fractions and negative values are rejected. A duration that is compared with a measurement, such as a recovery target, uses only hours, minutes, and seconds. A retention or support period may use years, months, weeks, and days. A computed duration is not stored. A measured length of time is a quantity with a UCUM time unit, not a duration.

An interval is a pair of the same type. The end is optional. A timestamp interval includes the start and excludes the end. A date range includes its first day and its last day. The end does not precede the start. Milestone sequences are validated in order. Existing pair names stay. A missing end means the interval is open. Measurement periods use period_start and period_end as a half-open timestamp interval.

A time zone is a canonical IANA name from the pin in @7lens/contracts. Offsets and abbreviations are not time zones. A recurring local schedule, when modelled, keeps wall-clock time plus that zone.

The Organization time zone defines “today” and the day and calendar-quarter boundaries in derived views and Lens answers. When the preference is unset, that zone is UTC. Facts are bucketed by one named timestamp per record type. Observations are bucketed by period_start. Stored values, stored derived values, and exports do not depend on the Organization zone. A stored derivation evaluates dates in UTC. Changing the Organization time zone re-buckets views and is recorded in the Configuration change log. It does not rewrite stored data.

The Inventory discovery filter excludes its end. An as-of parameter accepts only a timestamp with an offset. Contract-specific dates are not a convention in this document.

Tightening of these rules warns on existing data and errors on new writes once that validation is in place.

Naming

No global rename is in force. Existing field names, vocabulary values, and id values stay valid until their own versioned migration.

New external JSON and YAML fields, new 7lens-authored semantic ids, and new closed-list values use snake_case. A new reference is *_id or *_ids. A token taken from an external standard stays verbatim (EUR, Europe/Madrid, api-key, sha-256).

Published camelCase names stay valid until a versioned migration and are tracked as compatibility exceptions. Inventory is the migration that already happened: the live Inventory document is snake_case, including asset_id, asset_type_id, offering_id, deployment_refs, relationship_id, from_asset_id, to_asset_id, valid_from, and valid_to. The v1 names assetId, deploymentRefs, externalIds, discoveredAt, lastSeenAt, and markedForDeletion are not written. Configuration axes are not renamed by that migration. Platform serviceIds and offeringIds stay until their own migration. A Stack id is one snake_case segment. A Service id is two dot-separated segments. An Offering id is three segments, and the first two equal its Service id. An Asset Type id is the Service id, a dot, and one snake_case segment.

Internal TypeScript stays camelCase, with PascalCase types, components, and Zod names that end in Schema. Prettier’s tabs win. File names are kebab-case or PascalCase. There are no TypeScript enums; a closed list is z.enum. Generated code is exempt. A property that mirrors wire data is exempt from the camelCase lint.

A new 7lens-minted asset id matches ^a-[a-z0-9]{16}$: the prefix a- plus 16 lowercase letters or digits. The id encodes no category, asset type, offering, or stack. An existing id is not parsed for hidden meaning. Source-system keys are not the asset id and are not provenance’s source record id. The object shape of those keys, and the rest of the identity-and-references category, stay open.

People and accountability

A person in 7lens is always this shape:

Field	Required
name	Yes
surname	Yes
email	Yes
role	No

The field name is accountable_person. In the Configuration UI that field is labelled Owner. A later owner role (technical, financial, and similar) is another named slot of this same shape. Email correlates records. It is not a foreign key to a person registry. There is no Person registry and no Team entity.

New Configuration writes reject free-text owner, accountable, and ownerPerson, and they reject ownership mirrors. The person, when one is stored, is accountable_person.

An Asset stores no person. Belonging is a reference to an Application, a Domain, or a Platform. The wire name owner for that reference is retired. Accountability walks the belonging entity’s accountable_person: the Application, otherwise the Domain; the Platform when the Asset belongs to a Platform. Assessed provenance names the assessor with accountable_person.

Access principal is the authenticated user or client. It is the actor for permissions, audit, and the Configuration change log. It is not ownership and it is not Asset belonging.

Provenance

Provenance follows W3C PROV concepts without PROV serialization. Technology definition provenance and Inventory fact provenance are one concept family. Existing field names and their casing stay.

Every posture value, and every Inventory fact that carries provenance, states an origin:

Origin	Required with it
observed	Source system, source record id, and the observed timestamp.
assessed	Assessor as accountable_person, and the assessed timestamp.
derived	A named rule id and the evaluation timestamp.

An observed attribute may omit its own provenance block when that block would repeat the Asset row’s provenance. The reader inherits the row. Per-attribute provenance is required when the origin is assessed or derived, or when the source differs from the Asset row.

A derived posture value may be stored on the Asset, with history, and it documents how it is calculated from Asset attributes. Roll-ups, counts, Lens KPIs, and the exposure view are computed and are not stored.

confidence is optional: high, medium, or low. Absent means unknown. Evidence fidelity on a fact record is actual, estimate, or simulated. Fidelity does not stand in for confidence.

discovery_method is declared, imported, discovered, or manual. Technology last_verified is a calendar date. Inventory observation times are timestamps. authoritative_source may be recorded on an Inventory fact. The source record id is the row that produced the fact. It is not an external id.

Freshness is computed from last confirmed or observed time against the view’s as-of. It is not stored. Validation status is computed by the shared validator against the declaration version in force when the value was recorded. It is not stored on the value.

Technology definition provenance stays optional. A missing Offering provenance block warns and does not block save.

Asset value history carries the value, the origin provenance, last_confirmed, and declaration_version. Technology characteristic values have no value history. Configuration backup and the Configuration change log cover them. The change log records who, when, and the value before and after, and it is browsable per entity. Raw source payloads stay as received.

Write precedence for one attribute is closed:

1. assessed, until the assessment expires or an operator clears it.
2. observed from the designated authoritative_source.
3. Other observed values, by the latest timestamp.

A lower-precedence observation updates last_seen_at. It does not replace the active value. How long an assessment stays in force before it expires is not set.

Lifecycle

Status and lifecycle are separate closed lists, one per record kind, pinned in @7lens/contracts. A status is never a recognition key. Existing values stay. A documentation map to common CMDB lifecycle names may be published later. The stored values are not renamed to those names.

Service and Offering lifecycle_state:

Value
draft
pilot
production
sunset
retired

Asset status is a different list. The values kept today are running, ready, stopped, retired, deleted, and unknown. retired and deleted are the terminal operating states. The allowed transitions among these values are not published. A status change is kept in history. status_reason is optional on retired or deleted. An id is not reused after either terminal state.

Finding, demand, execution, and Contract statuses stay their own lists. Environment is placement on a Deployment (sandbox, dev, pre, pro, decom), not a status. An Asset inherits environment from its Deployments.

Validity follows the time rules. Configuration valid_from and valid_to are inclusive calendar dates. Inventory relationship valid_from and valid_to are half-open timestamps. A missing end is open-ended.

Configuration entities do not store created_at or updated_at. Authorship is the Configuration change log and backup, with the document revision used for concurrency. An Inventory Asset keeps discovered_at and last_seen_at, and it may add optional created_at and retired_at. Fact-record milestone times stay. History entries are UTC timestamps.

Deletion has three meanings:

Meaning	What happens
Configuration removal	The record is removed after confirmation.
Broken Configuration link	The Inventory row is orphaned and may be marked_for_deletion, which is a cleanup queue. The Configuration write is still allowed.
End of operation	Asset status becomes retired or deleted.

deleted and marked_for_deletion are independent. Removal of an Asset is retired or deleted, then a restorable queue, then purge. Purge of marked_for_deletion rows runs only when someone runs cleanup. Asset ids are not reused.

Asset value history is kept for seven years (P7Y). Older entries may be purged when someone runs cleanup. The current value is never removed by that rule. Configuration backup, the change log, and raw-ingest lifetime are separate retention rules.

Quantities

A quantity is { value, unit }. value is a finite number. unit is a UCUM code from the pin below. Money is not a quantity. An authored duration stays a duration. A measured length of time is a quantity with a time unit.

The pin is stored as { code, dimension, base_unit, conversion_factor }. Dimensions are time, data_size, percent, ratio, and count. conversion_factor is an exact integer multiplier into base_unit. Binary data sizes use powers of 1024. TiBy is 1024^4 bytes.

Code	Dimension	Base	Factor
s	time	s	1
min	time	s	60
h	time	s	3600
d	time	s	86400
By	data_size	By	1
KiBy	data_size	By	1024
MiBy	data_size	By	1024^2
GiBy	data_size	By	1024^3
TiBy	data_size	By	1024^4
%	percent	%	1
1	ratio	1	1
{ticket}	count	{ticket}	1
{1}	count	{1}	1

A percentage is stored with unit % on a 0–100 scale. A simple ratio uses the dimensionless unit 1. A count uses a UCUM annotation such as {ticket} or {1}. Count annotations do not convert into each other.

The full finite number is stored. Rounding happens at display. A declaration may constrain range and fractional digits. It does not coerce in silence. Ingest keeps the observed number and unit. Views convert with conversion_factor. A preference does not rewrite a stored unit. Customers do not invent units outside this pin.

A quantity declaration sets a fixed unit, or a unit_dimension with an allowed_units subset of that dimension. CVSS-like and EPSS-like scores stay numbers with declaration constraints. They are not UCUM quantities. A metric that a view can compute is not newly authored as an observation. Monetary observations use the money shape.

Existing rows whose unit is free text warn. A new write whose unit is outside the pin errors once that validation is in place.

Money

Money is { amount, currency }. amount is a finite number in major currency units. currency is a required ISO 4217 alphabetic code from the pin in @7lens/contracts. There is no schema default currency.

Organization display_currency is a preference. It affects rendering and view aggregation. It does not rewrite a stored amount. When it is unset, each amount renders in its stored currency, and a cross-currency total is not mixed in silence.

Currency conversion is a derived view. Every converted figure states its rule, its rate source, and its rate date. A converted amount is not stored by default. A stored derived monetary value follows the provenance rules and still carries the rate source and the rate date. Aggregation uses full precision, then converts, then rounds. Rounding uses the currency’s fraction digits from the pinned ISO 4217 data, and it happens only at display.

The first closed rate-source value is ecb_reference, used when a feed is wired. Until a feed exists, a cross-currency total is withheld or shown per currency. An unknown currency is left unknown. It is not relabelled as EUR. An amount with more fractional digits than the currency allows warns now and errors on a new write once money validation is in place.

Pricing quantity units for a price-times-quantity figure stay on Contracts. A monetary metric observation uses this money shape. Contract modelling itself remains a separate decision.

Attribute definitions

One declaration language lives in @7lens/contracts. It is used for Technology characteristics, Asset Type attributes, Lens extensions, and customer extensions. There is no second language and no second value-type set. OSM does not define a characteristic language. Core declarations ship in @7lens/contracts with the other pins. A customer declaration is Configuration on the entity it extends. The Conventions view lists the core read-only. Values stay on the entity that holds them: a Service or Offering characteristic value is a sibling of the declaration; an Asset value is on the Asset.

A declaration has:

Field	Rule
name	Matches ^[a-z][a-z0-9_]*\.[a-z][a-z0-9_.]*$.
description	Required.
definition_uri	Optional. A plain URL.
value_type	One of the closed set below.
requirement_tier	mandatory, recommended, or optional.
required	Paired with the tier.
Cardinality	min_cardinality and max_cardinality.
mutability	Stated on the declaration.
status	active or deprecated.
default	Optional, and only when the declaration is configurable.

Value types: string, integer, number, boolean, date, datetime, duration, uri, version, quantity, money, reference. enum and list remain readable aliases. A reference names its target kind or kinds. Changing a value type requires a new name. Values validate against the declaration_version in force when they were recorded.

Reserved prefixes for built-ins:

core, security, roi, agents, ops, capacity, compliance, hosting, identity, software.

A customer declaration starts with custom. or <organization_id>. (for example custom.cost_center or example.sap_tier).

Vocabulary binding is exclusive. The declaration sets vocabulary_id to the id of one pinned list, or it lists inline allowed_values. Not both. An Offering’s permitted values may only subset that set. External-standard tokens stay verbatim. A 7lens-authored list is snake_case.

requirement_tier pairs with required:

Tier	required	When the value is missing
mandatory	true	Error on a new write. Warning on existing data.
recommended	false	Warning. Save is not blocked.
optional	false	Silent.

A declaration holds no value field. On a Service or Offering the stored value is the fixed sibling key configured_value. The declaration name is not the YAML property key. An Asset Type declaration carries no value. The Asset stores the value inside attributes[]. There is no structural split between descriptive attributes and posture attributes.

The envelope uses snake_case keys: name, value, declaration_version, last_confirmed, origin (observed, assessed, or derived), and provenance. Origin and provenance follow the provenance category.

A customer extension, and an Offering’s permitted values, may only narrow: subset allowed_values or the vocabulary, raise min or min_length, lower max, max_length, or max_fractional_digits, or tighten required from false to true. They do not widen, and they do not change value_type or unit dimension.

Constraints are the closed set min, max, pattern, min_length, max_length, and max_fractional_digits. Nothing is coerced in silence. Object-typed attributes and conditional constraints are deferred. A quantity declaration takes its unit from the UCUM pin. A money declaration leaves currency on the value and may constrain the allowed currencies. Other value types do not take a free-text unit.

No characteristic name is mandatory on every Service or Offering. ops.availability_target is a valid example of a recommended quantity. It is not a core declaration and not a required field.

The starting vocabulary pin is the approved catalog. A declaration binds a list with vocabulary_id. These ids are already assigned:

vocabulary_id	Tokens
cpu_architecture	amd64, arm64, arm, 386, ppc64le, s390x, riscv64
os_family	linux, windows, darwin, freebsd
data_classification	public, internal, restricted, confidential, secret
exposure	public, internal, vpn, partner
human_oversight	human_in_the_loop, human_on_the_loop, human_in_command, none

The same catalog pins these lists. Their vocabulary_id strings are:

vocabulary_id	Tokens
component_type	library, framework, runtime, application, operating_system, container, firmware, file, machine_learning_model, data
vulnerability_id_scheme	cve, ghsa, osv
severity	critical, high, medium, low, informational
vex_status	not_affected, affected, fixed, under_investigation
tool_protocol	mcp, a2a, openapi, function, custom
operation_effect	read, create, update, delete, execute
auth_method	oauth2, api-key, mtls, basic, iam, none
identity_kind	service_account, managed_identity, app_registration, workload_identity, api_key, bot_user, other
hash_algorithm	sha-256, sha-384, sha-512

Component type runtime corresponds to CycloneDX component type platform. The 7lens token stays runtime so it does not collide with a Platform. Severity informational corresponds to a CVSS qualitative rating of None. Auth method and hash algorithm keep the standard’s hyphens.

These are adopted by reference. Their registries are not copied into this document: PURL, CPE, SPDX license expressions, os-release ID and VERSION_ID, ISO 3166-1 alpha-2 country codes in lowercase, ISO 4217, UCUM, IANA time zones, CVSS version / vector / baseScore, CISA KEV listed / dateAdded, and EPSS score / percentile / scoredOn.

data_classification is the five-value set above. This document does not map those values onto another classification list.

Lists already closed elsewhere stay as they are: Deployment roles runtime and source, the provenance lists in this document, and the lifecycle lists in this document. Adding a vocabulary is a core change.

One validator compiles declarations for YAML, the API, backup, and the UI, and it can export JSON Schema and MCP schemas. Validation status is computed. Existing data warns. A new write errors once declaration validation applies. enum and list remain readable aliases of the value type. Inventory v2 does not write category, profile, or technologyRef.

Customer preferences

Tenant preferences are an optional preferences object on the Organization. Keys are snake_case.

Key	Pin	When unset
time_zone	IANA	UTC. This zone governs shared Lens buckets.
display_currency	ISO 4217	Amounts render in their stored currency. Cross-currency totals are withheld until a rate feed exists.
locale	BCP 47	en-US. This drives date and number formats.
language	—	en. The UI stays English until translations exist.

A preference changes presentation and derived-view aggregation only. Stored data, YAML, backup, and API and MCP payloads stay canonical. Fiscal-year start and week start are out of scope.

The Conventions control is settings for the Configuration page, placed in a corner. It is not a fifth axis and not a peer of the four axes. A Configuration admin (config.write, scope all) edits tenant preferences. Core conventions and customer declaration sets appear there read-only, with links to the place each one is authored. Save confirms that the effect is presentation only. Preference edits go to the Configuration change log when that log is in place. Backup is the durable copy in the meantime.

A signed-in user’s personal time_zone and language would change only that user’s rendering. Those overrides are omitted until a user profile exists. Organization time_zone remains the zone for shared Lens buckets.

Contracts, Inventory, and Processes are further views on the same Configuration page. Their layout is decided before that page is built. It is not a convention rule.

---

Rules

Topic	Rule
Stored time	Timestamps are RFC 3339 with an offset. 7lens writes UTC Z at millisecond precision. Dates are YYYY-MM-DD.
Preferences	Presentation and aggregation only. No rewrite of stored values.
New names	snake_case fields, snake_case semantic ids, *_id / *_ids references. External tokens stay verbatim.
Asset id	^a-[a-z0-9]{16}$. Opaque.
Person	accountable_person with name, surname, email, optional role.
Declaration name	^[a-z][a-z0-9_]*\.[a-z][a-z0-9_.]*$, reserved prefix, custom., or an organization id.
Vocabulary	vocabulary_id or allowed_values, never both.
Requirement	mandatory errors on new writes. recommended warns. optional is silent.
Declaration value	No value inside the declaration. configured_value on a Service or Offering. attributes[] on an Asset.
Narrowing	Extensions subset or tighten. They do not widen or change type or unit dimension.
Quantity	{ value, unit } from the UCUM pin, including TiBy. Ingest does not convert.
Money	{ amount, currency }. No default currency. Cross-currency totals wait for a stated rate.
History	Asset values kept P7Y. Current value stays. Technology characteristics use backup and the change log.
Precedence	Assessed, then authoritative observed, then other observed. Lower precedence updates last_seen_at only.

YAML, backup restore, the API, and the Configuration page share one validator for a given convention. Warnings apply to existing data. Errors apply to new writes once that check is in place.

---

Q&A

Q1. Does the Organization time zone change a stored timestamp?

No. It changes how derived views bucket facts, and how a timestamp is displayed. Stored values and exports stay canonical. Personal zone overrides are omitted until a user profile exists.

Q2. Where does a characteristic’s number go?

The declaration describes the attribute and holds no number. On a Service or Offering the number is configured_value. On an Asset the number is inside attributes[].

Q3. Does a missing recommended attribute block save?

No. recommended warns. mandatory errors on a new write and warns on existing data. optional is silent.

Q4. Can a customer declaration use the ops prefix?

No. ops is reserved for built-ins. A customer name starts with custom. or the organization id.

Q5. What does a new asset id look like?

a- and 16 lowercase letters or digits, for example a-7f3c1ab9e0d24681. It does not encode type, offering, or stack.

Q6. How is a percentage stored?

As a quantity with unit % on a 0–100 scale. The unit 1 is a dimensionless ratio, not a second way to write a percentage.

Q7. When is a cross-currency total shown?

When a rate feed is wired and the figure states its rule, rate source, and rate date. Until then, totals stay per currency. The first rate source is ecb_reference.

Q8. Is ops.availability_target a required characteristic?

No. It is an example of a recommended quantity declaration. No characteristic name is mandatory on every Service or Offering.

Q9. Can the next observation replace an assessed value?

An automated observed write does not replace an assessed value unless the assessment has expired or an operator clears it. The expiry duration is not set. A lower-precedence observation still updates last_seen_at.

Q10. Is Asset status the same list as Service lifecycle?

No. Service lifecycle_state is draft, pilot, production, sunset, retired. Asset status is its own list, with retired and deleted as the terminal states. The transition graph is not published.

---

Examples

The numbers, the people, and ops.availability_target are examples. They are not required content.

Time, quantity, money, and a person

observed_at: '2026-10-30T14:00:00.000Z'
valid_from: 2026-01-01
valid_to: 2026-12-31
recovery_target: PT4H
measured_duration:
  value: 90
  unit: s
price:
  amount: 12.5
  currency: EUR
accountable_person:
  name: Ana
  surname: Ruiz
  email: ana.ruiz@example.com
  role: Service owner

PT4H is a duration. Ninety seconds is a quantity. The two shapes are not interchangeable.

Declaration and sibling value

characteristics:
  - name: ops.availability_target
    description: Availability the enterprise expects from this capability, on a 0-100 percent scale.
    value_type: quantity
    unit: '%'
    requirement_tier: recommended
    required: false
    # Example value. This name is not a core declaration.
    configured_value:
      value: 99.9
      unit: '%'

Asset attribute envelope

asset_id: a-7f3c1ab9e0d24681
attributes:
  - name: hosting.architecture
    value: arm64
    declaration_version: '1'
    last_confirmed: '2026-10-30T14:00:00.000Z'
    origin: observed

arm64 is a token of cpu_architecture. The Asset Type declaration that names hosting.architecture carries vocabulary_id: cpu_architecture and no value.

Organization preferences

preferences:
  time_zone: Europe/Madrid
  locale: en-US
  language: en

display_currency is omitted here, so amounts stay in their stored currencies.

Invalid shapes

# Value stored inside the declaration
- name: ops.availability_target
  value: 99.9

# Two vocabulary authorities
- name: security.max_data_classification
  vocabulary_id: data_classification
  allowed_values: [public, internal]

# Reserved prefix on a customer declaration
- name: ops.cost_center

# Asset id that encodes a type
asset_id: compute.virtual_machines.i-123

# Percentage written as a fraction
availability:
  value: 0.999
  unit: "1"

---

Non-goals

This companion does not:

• Treat a starter-pack fill-in as a rule. ops.availability_target, a 99.9 figure, and any other example characteristic stay examples.
• Redefine Stack, Service, Offering, Asset Type, or Asset.
• Specify source-system key fields beyond opaque asset ids, snake_case new references, and the separation of source-system keys from the 7lens id.
• Publish the Asset status transition graph, the assessment-expiry duration, object-typed attributes, or conditional constraints.
• Map data_classification onto another classification list.
• Add a second declaration language, or take JSON Schema as the authoring language.
• Put fiscal-year start or week start into the model. Personal time-zone and language overrides stay omitted until a user profile exists.
• Rewrite stored money or time when a preference changes.