JSON Schema

[hexus]

Pragma's field definition format is similar to JSON Schema and JSON Editor.

Investigate the overlaps and consider switching over to, and extending, JSON Schema. This could be pretty powerful, but also a overcomplicated due to its extensive feature set (e.g. external references).

• https://json-schema.org/
• https://github.com/json-editor/json-editor

Really, the best thing about this approach would be type safety and validation. The worst thing would be potential complexity. Some of this complexity could be avoided if a simplified format could be processed into full JSON Schema.

We could then also provide a meta-schema for the field definitions themselves.

Examples of changes

Rough examples of what certain fields types look like now, and what they'd look like with JSON schema.

Before

profile:
  type: section
  label: Profile
  description: Character profile

profile.name:
  type: string
  label: Name
  description: The character's given or chosen name

profile.alignment:
  type: selection
  label: Alignment
  description: The character's general and moral attitude
  options:
    options:
      lawfulGood: Lawful Good
      neutralGood: Neutral Good
      chaoticGood: Chaotic Good
      lawfulNeutral: Lawful Neutral
      trueNeutral: True Neutral
      chaoticNeutral: Chaotic Neutral
      lawfulEvil: Lawful Evil
      neutralEvil: Neutral Evil
      chaoticEvil: Chaotic Evil

After

JSON Schema always defines the root, whereas Pragma currently implies one. We can still imply one, we just embed the form fields into the properties of a type: object.

type: object
title: Pathfinder Character Sheet
description: JSON Schema for Pragma forms for the Pathfinder roleplaying game.
properties:
  profile:
    type: object
    title: Profile
    description: Character profiles
    properties:
      name:
        type: string
        title: Name
        description: The character's given or chosen name
      alignment:
        type: string
        title: Alignment
        description: The character's general and moral attitude
        enum: [
          'lawfulGood', 'neutralGood', 'chaoticGood', 'lawfulNeutral', 'trueNeutral', 'chaoticNeutral',
          'lawfulEvil', 'neutralEvil', 'chaoticEvil'
        ]
        options: # This is where any Pragma-specific data would reside
          enumLabels: [
            'Lawful Good', 'Neutral Good', 'Chaotic Good', 'Lawful Neutral', 'True Neutral', 'Chaotic Neutral',
            'Lawful Evil', 'Neutral Evil', 'Chaotic Evil'
          ]

It's much more verbose, and introduces the nesting that Pragma's format tries to avoid, but we could find a middle ground that compiles to JSON schema. For example:

profile:
  type: object
  title: Profile
  description: Character profiles

profile.name:
  type: string
  title: Name
  description: The character's given or chosen name

profile.alignment:
  type: string
  title: Alignment
  description: The character's general and moral attitude
  enum: [
    'lawfulGood', 'neutralGood', 'chaoticGood', 'lawfulNeutral', 'trueNeutral', 'chaoticNeutral',
    'lawfulEvil', 'neutralEvil', 'chaoticEvil'
  ]
  options: # This is where any Pragma-specific data would reside
    enumLabels: [
      'Lawful Good', 'Neutral Good', 'Chaotic Good', 'Lawful Neutral', 'True Neutral', 'Chaotic Neutral',
      'Lawful Evil', 'Neutral Evil', 'Chaotic Evil'
    ]

What we avoid here is properties, or in the case of Pragma's current format: children. We instead rely on full paths like profile.alignment to set the expected properties for different objects.

tag, which is usually something like 'pragma-section' or 'pragma-string', could then become JSON Schema's/JSON Editor's format, which could translate to a theme of tag names to decide how to render.

Considering how such schemas might translate to a server-side implementation, however, this falls apart a bit. E.g. type: string and format: datetime, where a server-side representation might just see this instead as a Date type. However, this isn't too much of a problem, as we're specifying a JSON format.