DocsThe data protocol

view/v2

packages/core/schema/view-v2.schema.json

On this page

Which piece of data each dimension shows. One per person, for every flower they look at; a default for everyone else. The data never names a dimension and the look never sees a data name: the view joins them. A dimension whose piece of data a flower lacks, or has as a kind the dimension doesn't accept, shows nothing on that flower. Kinds are checked when a view meets a flower's data, by the table in specs/006-the-map/contracts/view.md; the schema holds the shape. v2 adds labels: which piece of data names each petal (a category), so a person's annotations can name them. A view/v1 reads as v2 with labels on identity. See specs/006-the-map/contracts/view.md.

Fields

Field	Type or allowed values	Presence in its parent	Description
`petal`	"view/v2"	Required
`dimensions`	object	Required	The ten dimensions, all present. null means the dimension isn't in use.
`dimensions.height`	choice	Required
`dimensions.height (variant 1)`	null	Required
`dimensions.height (variant 2)`	object	Required
`dimensions.height (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.height (variant 2).scale`	"sqrt" / "linear" / "log"	Optional	How a number becomes the dimension's value, with spec/v1's meanings.
`dimensions.width`	choice	Required
`dimensions.width (variant 1)`	null	Required
`dimensions.width (variant 2)`	object	Required
`dimensions.width (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.width (variant 2).scale`	"sqrt" / "linear" / "log"	Optional	How a number becomes the dimension's value, with spec/v1's meanings.
`dimensions.width (variant 2).max_ratio`	number	Optional	widest side over narrowest side, so the polygon holds
`dimensions.order`	choice	Required
`dimensions.order (variant 1)`	null	Required
`dimensions.order (variant 2)`	object	Required
`dimensions.order (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.colour`	choice	Required
`dimensions.colour (variant 1)`	null	Required
`dimensions.colour (variant 2)`	object	Required
`dimensions.colour (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.colour (variant 2).scale`	"sqrt" / "linear" / "log"	Optional	How a number becomes the dimension's value, with spec/v1's meanings.
`dimensions.outline`	choice	Required
`dimensions.outline (variant 1)`	null	Required
`dimensions.outline (variant 2)`	object	Required
`dimensions.outline (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.texture`	choice	Required
`dimensions.texture (variant 1)`	null	Required
`dimensions.texture (variant 2)`	object	Required
`dimensions.texture (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.markings`	choice	Required
`dimensions.markings (variant 1)`	null	Required
`dimensions.markings (variant 2)`	object	Required
`dimensions.markings (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.segments`	choice	Required
`dimensions.segments (variant 1)`	null	Required
`dimensions.segments (variant 2)`	object	Required
`dimensions.segments (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.lines`	choice	Required
`dimensions.lines (variant 1)`	null	Required
`dimensions.lines (variant 2)`	object	Required
`dimensions.lines (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).
`dimensions.labels`	choice	Required
`dimensions.labels (variant 1)`	null	Required
`dimensions.labels (variant 2)`	object	Required
`dimensions.labels (variant 2).data`	string	Required	A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam).

Examples

view.v2.json

Fixture source

{
  "petal": "view/v2",
  "dimensions": {
    "height": {
      "data": "share",
      "scale": "sqrt"
    },
    "width": {
      "data": "share",
      "scale": "log",
      "max_ratio": 2
    },
    "order": {
      "data": "share"
    },
    "colour": {
      "data": "kind"
    },
    "outline": {
      "data": "identity"
    },
    "texture": null,
    "markings": null,
    "segments": null,
    "lines": null,
    "labels": {
      "data": "identity"
    }
  }
}

view.v2.names.json

Fixture source

{
  "petal": "view/v2",
  "dimensions": {
    "height": {
      "data": "share",
      "scale": "sqrt"
    },
    "width": {
      "data": "share",
      "scale": "log",
      "max_ratio": 2
    },
    "order": {
      "data": "share"
    },
    "colour": {
      "data": "kind"
    },
    "outline": {
      "data": "name_kind"
    },
    "texture": null,
    "markings": null,
    "segments": null,
    "lines": null,
    "labels": {
      "data": "name"
    }
  }
}

Full schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:petal:schema:view:v2",
  "title": "Petal view v2",
  "description": "Which piece of data each dimension shows. One per person, for every flower they look at; a default for everyone else. The data never names a dimension and the look never sees a data name: the view joins them. A dimension whose piece of data a flower lacks, or has as a kind the dimension doesn't accept, shows nothing on that flower. Kinds are checked when a view meets a flower's data, by the table in specs/006-the-map/contracts/view.md; the schema holds the shape. v2 adds labels: which piece of data names each petal (a category), so a person's annotations can name them. A view/v1 reads as v2 with labels on identity. See specs/006-the-map/contracts/view.md.",
  "type": "object",
  "required": [
    "petal",
    "dimensions"
  ],
  "additionalProperties": false,
  "properties": {
    "petal": {
      "const": "view/v2"
    },
    "dimensions": {
      "type": "object",
      "description": "The ten dimensions, all present. null means the dimension isn't in use.",
      "required": [
        "height",
        "width",
        "order",
        "colour",
        "outline",
        "texture",
        "markings",
        "segments",
        "lines",
        "labels"
      ],
      "additionalProperties": false,
      "properties": {
        "height": {
          "$ref": "#/$defs/sized"
        },
        "width": {
          "$ref": "#/$defs/width"
        },
        "order": {
          "$ref": "#/$defs/plain"
        },
        "colour": {
          "$ref": "#/$defs/sized"
        },
        "outline": {
          "$ref": "#/$defs/plain"
        },
        "texture": {
          "$ref": "#/$defs/plain"
        },
        "markings": {
          "$ref": "#/$defs/plain"
        },
        "segments": {
          "$ref": "#/$defs/plain"
        },
        "lines": {
          "$ref": "#/$defs/plain"
        },
        "labels": {
          "$ref": "#/$defs/plain"
        }
      }
    }
  },
  "$defs": {
    "data": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120,
      "pattern": "^[a-z0-9_.-]+(:[a-z0-9_.-]+)?$",
      "description": "A piece of data by its name, as the flower's data names it (share, amount, kind, identity, backers, or a layer's own name), or <layer>:<name> when two layers use the same name (005's seam)."
    },
    "scale": {
      "enum": [
        "sqrt",
        "linear",
        "log"
      ],
      "description": "How a number becomes the dimension's value, with spec/v1's meanings."
    },
    "plain": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "data"
          ],
          "additionalProperties": false,
          "properties": {
            "data": {
              "$ref": "#/$defs/data"
            }
          }
        }
      ]
    },
    "sized": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "data"
          ],
          "additionalProperties": false,
          "properties": {
            "data": {
              "$ref": "#/$defs/data"
            },
            "scale": {
              "$ref": "#/$defs/scale"
            }
          }
        }
      ]
    },
    "width": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "required": [
            "data"
          ],
          "additionalProperties": false,
          "properties": {
            "data": {
              "$ref": "#/$defs/data"
            },
            "scale": {
              "$ref": "#/$defs/scale"
            },
            "max_ratio": {
              "type": "number",
              "minimum": 1.5,
              "maximum": 3,
              "description": "widest side over narrowest side, so the polygon holds"
            }
          }
        }
      ]
    }
  }
}