The project file: JSON and YAML

Exporting and importing a project

Export › Whole project writes a whole project as one file, as Portable JSON or Portable YAML. To bring it back, open Start from a template or import on the home screen, choose Entalpa file, and drop in a .json, .yaml or .yml file. Importing always creates a new project: it never merges into an existing one. A coding agent does the same over MCP, with projects_export and projects_import.

JSON or YAML

The two are one document written two ways: the same keys, in the same order, read back through the same import. JSON suits tools and scripts. YAML is for people: to keep the spec in a repository beside the code, and review its changes in a pull request. An agent asks for it with format: yaml, and gets the file with a name to commit it under, such as clinicflow-project.yaml for a project called ClinicFlow.

Part of a requirement, in YAML:

requirements:
- human_id: Req-001
  content:
    requirement: The system shall let a patient book a free appointment slot.
    acceptance: |-
      Given a free slot on Monday at 10:00
      When the patient books it
      Then the slot shows as taken to every other patient
    category: functional
    priority: must
    rationale: Patients book outside opening hours.
  source_story_ids:
  - S-001
  lifecycle: reviewed

The YAML is written to read well in a diff:

• Text of several lines, such as acceptance criteria, is a block, one line per line, not one long string with \n in it.
• A long line is never wrapped, so changing one word changes one line of the diff, not the paragraph around it.
• Text a YAML reader would take for something else, such as 1e3 or true, is quoted, so it comes back as text.

Edit the file by hand, if you like, and import it: a JSON file is valid YAML too, so the import reads either.

What it keeps

• Stakeholders, and stories with their priorities.
• Requirements: their text and fields, status, locks and flags, subsystem, source stories and source requirements.
• Subsystems and interface contracts.
• Open questions, with their answers and the stories they led to.
• The project's requirement fields, and its Spec score weights.
• The chat history, only when Include chat history is ticked.

What it leaves out

• Saved versions and the undo history. An imported project starts with a fresh Initial version.
• Suggestions waiting for review.
• The Spec score: the file carries it for reading, but an imported project is assessed again.
• Which requirements are suspect: every link starts clean.
• Members and shared links.
• For a Spec Kit import, the repository it came from, so Import new Spec Kit features is not offered.

Inside the file

Everything refers to everything else by its id, such as Req-004 or S-002, never by an internal one, and the lists are sorted, so two exports of the same project differ only where the project does. The keys are the same in JSON and YAML.

On import, the ids are kept and every reference is resolved by id. A reference to something not in the file is dropped, and the import lists each one it dropped.