CSV Resource Specification

Work-in-progress (WIP)

• Overview
• Columns
• Semantics
• Example

Overview

Origins defines a CSV format for representing a resource. This format is designed for manual creation and updates of resources as supposed to automatic generation from existing sources. In most cases, there are no systems that represent the resource needing to be created and thus requires a domain expert to manually create the resource.

Since the format is focused on simplicity for the most common needs, the feature set is a bit more limited than the JSON format. This format does not support:

• Automatically creating/updating the resource itself

Columns

• id - Unique identifier for the respective object being represented as a row. This must also be unique across rows to prevent ambiguity when referencing across rows such as in resource, start, and end.
• uuid - The UUID of an external component or relationship. If uuid is present, the id column can be used as a local identifier for the start and end columns for relationships.
• label - A human-readable label of the object.
• type - A classification type of the object.
• description - A verbose description of the object.
• parent - ID of the parent component. This only applies to component rows.
• start - ID of the start component. This only applies to relationships rows. This must be an id of a component defined in the file or a UUID of an external component.
• end - ID of the end component. This only applies to relationships rows. This must be an id of a component defined in the file or a UUID of an external component.
• directed (experimental) - A boolean denoted the relationship is directed. Default is false. This only applies to relationships rows.
• dependence (experimental) - A boolean denoting the components have a dependency on each other. That is, if a component changes, an event will be triggered on behalf of the other component. If directed is true, the dependence is one-way (end depends on start), otherwise it is a bi-directional dependence. This only applies to relationships rows. Default is false.
• properties - Arbitrary comma-separated key/value pairs representing the properties of the component or relationship. Values that contain spaces or commas must be quoted.

Semantics

• The file must have the header defined with the correct field names
• Rows that contain an UUID are treated as an external component or relationship
• Relationship rows must contain valid values in the start and end columns
• All other rows are treated as components and must not contain relationship-based values
• Property values are coerced into native types (boolean, number) based on simple heuristics

Example

id	uuid	label	type	description	parent	start	end	directed	dependence	properties
chinook		Chinook	Database
artist		Artist	Table		chinook
artist/artistid		Artist Id	Column		artist					primary_key=true, data_type=integer
artist/name		Name	Column		artist
album		Album	Table		chinook
album/artistid		Artist Id	Column		album
album/artistid:artist/artistid		Foreign Key	foreignkey			album/artistid	artist/artistid	true	false
postgres_artist	abc123-def
postgres_sqlite_artist		Semantic Link	semlink			artist	postgres_artist	false	true	similarity=1.0
mysql_sqlite_artist		Semantic Link	semlink			artist	ae81fe-19a	false	true	similarity=1.0

Explanation

• The first 7 rows are defined for this resource
• Row 8 is an external component with a UUID defined and specifies a local id to more easily reference the row in the relationship below (row 9)
• Row 9 is relationship between a local component and the external one defined in row 8
• Row 10 is a relationship between a local component and an external one not included to this resource explicitly.