Core Concepts¶

This page defines the core terms used throughout the rest of the documentation.

If Overview gives you the map, this page gives you the vocabulary used throughout the docs.

1. Resource¶

A resource is the long-lived logical entity your application manages, such as a user, document, job, or configuration object.

A resource keeps the same identity even when its content changes.

A revision is one version of a resource at a specific point in time.

This distinction matters because the resource ID stays stable while the actual content evolves through multiple revisions.

By default, operations such as update and patch create a new revision rather than overwriting history.

SpecStar keeps metadata separate from the main resource payload.

Metadata includes values such as:

This separation makes lifecycle operations, search behavior, and operational tooling easier to keep consistent.

The ResourceManager is the enforcement layer for resource behavior.

It coordinates:

Once you understand the manager’s role, most SpecStar behavior becomes much easier to predict.

A schema version tells SpecStar how a revision’s data shape relates to the current model definition.

This becomes important when your application evolves and you need migration paths between versions.

SpecStar search is built around indexed metadata rather than full payload scans.

That design keeps search behavior more predictable and encourages you to identify important searchable fields explicitly.