A dream journal begins with a person's account, not a complete measurement of an experience. The account may be fragmentary, uncertain, corrected later, or intentionally brief. A useful Lucid Dream API design accommodates that uncertainty instead of forcing every entry into an apparently complete record. The schema should make honest omissions possible and prevent downstream software from confusing them with negative answers.

Consider a user who remembers a staircase and a conversation but does not remember whether they knew they were dreaming. Storing lucidity as false would answer a question they never answered. Storing an explicit unspecified value preserves the distinction. This guide proposes a journal format for an implementation you control, with emphasis on clear meaning rather than an exhaustive catalog of dream attributes.

Begin with the smallest useful record

A first record can contain an identifier, a revision, the original text, when the record was created, and an optional user-reported experience date. Those last two times describe different events. A person may write on Tuesday about something remembered from Sunday. Automatically treating the save time as the dream time would make later timelines misleading.

Keep identity and access information in the trusted application boundary. A client-supplied owner field should not decide who owns the resulting resource. For examples and tests, use synthetic identifiers that cannot be mistaken for real participants. Add descriptive fields only after you can explain how they will be collected, displayed, corrected, exported, and removed.

Represent unknown, absent, and empty distinctly

An absent optional property can mean the application did not collect it. A null value can mean the property was considered but its value is unavailable, provided the contract explicitly says so. An empty string usually deserves separate treatment: it may be valid empty content, accidental input, or a validation error. Pick meanings deliberately instead of allowing each client to invent its own interpretation.

The JSON Schema object reference explains properties, required fields, and control over additional properties. In particular, declaring a property does not by itself make that property required. Use those mechanisms to express the structural contract, then document semantic rules such as what unspecified lucidity means in your application.

Use explicit categories for self-reports

For a simple design, lucidity could accept reported_lucid, reported_not_lucid, and unspecified. These labels describe what a person reported; they do not certify a sleep state. Avoid numeric scales unless the application explains their anchors and intended use. A number that looks precise can still represent a subjective judgment.

A record that does not guess

A compact example illustrates the separation:

{
  "entry_id": "entry_example_002",
  "revision": 1,
  "text": "A staircase, then a conversation I cannot recall.",
  "experience_date": null,
  "lucidity": "unspecified",
  "origin": "user_report"
}

Do not infer a missing experience date from the text. Keep a later user correction as a new revision. The original example is deliberately incomplete because incompleteness is a legitimate state, not always a defect to repair.

Separate annotations from the account

User tags and generated tags have different origins. Store them in distinct collections, or attach an explicit origin to each annotation. A user might write “train,” while a model suggests “travel.” Both can be useful, but the interface should allow a person to accept, reject, or edit the suggestion without rewriting their original text.

Generated annotations should identify the entry revision they describe. If revision two removes the train scene, annotations from revision one should not quietly remain current. A simple rule is to mark derived results stale when their source changes. The application can offer regeneration as a separate action rather than automatically replacing a user's editorial choices.

Avoid designing one permanent boolean that means every possible use is allowed. Saving a journal, sending selected text for an optional transformation, exporting an entry, and contributing data to research are distinct product decisions. Your implementation should represent the choices that actually exist, with clear purpose labels and a record of when a choice changed.

This is an engineering pattern, not a declaration that a particular schema satisfies a law. A product team must decide its actual uses before collecting meaningful permission. Do not invent a research-consent field when no research workflow exists. If processing has already occurred, changing a flag must also trigger the appropriate operational behavior rather than only changing what the settings screen displays.

Make validation helpful without expanding collection

Validate reasonable text lengths, supported enumeration values, recognized encodings, and required relationships. Return a precise error when an identifier has the wrong shape or a revision is missing. Do not demand a person's location, age, health history, or identity merely because those fields might be interesting later. Optional collection still needs a clear reason.

Validation can also check that a generated annotation references an existing source revision. It cannot establish that the account describes an actual dream. Keep structural validity separate from truth. A perfectly valid JSON document may contain a fictional example, a mistaken recollection, or private writing that should never be passed to a model.

Plan export before adding complicated fields

A useful export lets someone understand their records without your application. Include original text, meaningful timestamps, selected annotations, revision information, and a brief explanation of field meanings. Do not make proprietary numeric codes the only way to interpret a person's own journal. A documented JSON export and readable text representation can complement each other.

Test an export containing accented characters, emoji, an unknown date, and multiple revisions. Import it into a clean test environment and compare meaning rather than superficial formatting. If the process turns an unspecified value into false or drops a user's correction, the export is incomplete even when it technically parses. Treat round-trip testing as part of the schema design.

Follow deletion through derived data

Deleting an entry should prompt questions about summaries, embeddings, search indexes, cached previews, and queued work. Decide which derived artifacts must also become unavailable and which minimal operational records remain for a documented reason. Do not equate removing one database row with completing the entire deletion workflow.

For a simple implementation, make source-entry identifiers traceable across every derivative. Then test deleting an entry while a transformation is running. The worker should check the current authorization and resource state before publishing a result. Otherwise, a late result can recreate information that the user reasonably believed they had removed. The privacy and security article explores that failure mode further.

Review the schema with real interface questions

Ask a designer to render an entry with no known experience date, a developer to export it, and a reviewer to distinguish a user's tag from a generated tag. If they need undocumented assumptions, revise the contract. Schema design becomes more useful when people test everyday interactions instead of only debating ideal field names.

Create a small collection of synthetic edge cases: a one-word report, a long multilingual report, a corrected event date, an entry with no lucidity response, and a generated result rejected by the user. Keep these examples beside the schema so future changes can be checked against the same meanings. A migration should preserve uncertainty as carefully as it preserves text.

Conclusion: a good schema leaves room for the person

The goal of a Lucid Dream API is not to make a dream look more certain than the account supports. It is to preserve a person's words, record the origin of annotations, and make ordinary actions predictable. Unknown values, revisions, and deletion are central features of that design.

Start with the smallest record your product needs and expand through documented use cases. Keep the dream-data topic guide close to the contract, and review the faithful summary workflow before introducing generated interpretation. Structure should help the person remain in control of their account, not give software permission to finish the story for them.