Project and Versions

Resource

A project is a folder. Every resource file in it has the same three fields:

apiVersion: dialogue/v1   # <plugin>/<version>
kind: Dialogue            # what this resource is
data:                     # the resource itself
  id: 01_intro_scene

Which file a resource lives in does not matter. data.id is unique per kind and uses letters, digits, _ and -, never dots, because dots separate the parts of references.

Versions

Every .osf project has exactly one Versions block, normally in versions.osf. It pins the language version and every plugin the project uses, the way Terraform’s versions.tf pins providers. language, story and dialogue are required.

Every resource compiles with its apiVersion taken from this block, so upgrading a plugin is a one-line change in one file. The YAML side shows two of the resources it applies to:

Versions {
  language = "1"
  story    = "v1"
  dialogue = "v1"
}

apiVersion: story/v1
kind: Story
data:
  id: demo
  name: Demo

apiVersion: story/v1
kind: Character
data:
  id: kael
  name: Kael

With plugins

Plugins that are not built in, such as i18n, are listed in Versions and compile to a plugins/v1 Configuration. Using a block whose plugin is not listed (an I18n block without i18n, for example) is an error.

Versions {
  language = "1"
  story    = "v1"
  dialogue = "v1"
  i18n     = "v1"
}

apiVersion: plugins/v1
kind: Configuration
data:
  plugins:
    - i18n/v1

Resources

A project contains resources of these types:

Editor support

The JSON Schema gives completion and validation for YAML resources in VS Code, JetBrains and Neovim. Add this first line to a file:

# yaml-language-server: $schema=<relative path>/schema/osf-v1.schema.json