app logo
Docs

What is FSET

FSET is a shallow tree structure editor that produces target data, with simple modular composability

FSET's products:

  • FModel : A schema editor that helps system owners model and author JSON Schema using a nice subset for data modeling

FModel

FModel's visual is inspired by Algebraic Data Type to represent type definition with block based structural constraints.

A fmodel example:

A fmodel encodes a json schema definition, source: https://github.com/vega/schema

FModel itself has no syntax (it can be displayed however html is capable of, though FModel displays it like text based because of familiarity and cleanliness; text and symbols are already great). So, there is no schema language introduced here, and no syntax errors (one would argue that a little bit of allowed mistakes enables more productivity). It's like editting high level AST where each node is a semantic block. A block represents a target data. However, it's easier to model stuff when we think in terms of type. In the end fmodels get exported as definitions along with a root schema starting from an entrypoint. FModel provides ease of constructing schema, constraints that prevent errors, automated features and documentation.

Why not use JSON Schema keywords directly?

JSON Schema is a set of constraints based keywords, not only it contains "if", "then, "else", but also its keyword independence nature. That means a cartesian product of all keywords is enormous, like you can freely compose a bunch of logic gates encoding business rules at schema level. It's expressive, but you will be inclined to put logics that should rather be at application level in there. That does not fit data modeling mental model (something that is not a model of data may look like configuration or parameters) FModel picks a nice subset of it and provides visual representation (and block constraints) that guides our brain to think in terms of model and type over logical constraints. In our observation, majority of JSON Schema users have used it this way all along, but there is still a lot of confusion, especially for newcomers, trying to mix and match to form rules that are not sane.

Goals

While FModel helps system developers author schema in "data modeling" way, it still uses standard JSON Schema Vocabulary without customization or our own vocabulary. So it's still in "Validation" category, not in "Code Generation" category because validation is what JSON Schema is designed for. So today, FModel only exports JSON Schema original vocabulary (based on draft/2020-12, "Each release of the JSON schema specification is treated as a production release"). FModel output schema is suitable for configuration validation, api request / respond body, and also data shape like data visualization grammar.

Generally speaking, FModel exports standard, widely adopted, data modeling schema in json format. There is JSON Type Definition (rfc8927) which is designed for code generation, if there is enough demand, FModel could also export JTD, though we would have yet another standard because code generation under JSON Schema umbrella, they just started developing it and FModel will export that as well when some releases come out.

How about non JSON and/or binary format export?

No Plan!

Module and Ref

Module

FModel has a logical group called "modu", stands for module (naming is not a big deal it's just short enough for good noise/signal ratio visually). A module contains a list of fmodels (i.e. top level types). That's it. Not as much as a "module system". Module name is used with fmodel name at export. Currently, a list of module is flat, there is no folder for now. It's enough for majority of schema today (however, the editor will have a way to group module in future, maybe something like scoped labels, because module and ref belong to FSET that will also have other kind of editors)


Ref

A Ref type can refer to a fmodel across modules. It also provides a simple referential integrity enforced at database level (i.e. Postgresql's foreign key constraint), if a fmodel is being referenced, it's not removable. Ref name automatically reflects referenced fmodel name and namespace when type is updated or moved between modules.

Entrypoint

FModel currently support 1 entrypoint at a time when export as a single file schema. A fmodel can be marked as entrypoint, and it will be exported to root level of JSON Schema of its own module, the rest of fmodels will go under "$defs" keyword (currently, without tree shaking; unused defs elimination) each with module name namespace.

References

Export

FModel to JSON Schema (draft 2020-12)

FModel uses a stable subset of draft-2020-12; keywords that have been through from several previous releases to latest release. It would probably have some new keywords in future draft if that's useful in data modeling. Ideally, we do not ever remove keywords especially ones that strengthen constraints (i.e. fail a validation that's previously passed) 

  • {
  "properties": {
    "field_a": {
      "type": "string"
    },
    "field_b": {
      "maximum": 2147483647,
      "minimum": -2147483648,
      "type": "integer"
    }
  },
  "type": "object"
}
                    

  • {
  "maxItems": 3,
  "minItems": 3,
  "prefixItems": [
    {
      "const": "ok"
    },
    {
      "$ref": "https://localhost/ExportDocs#/$defs/Record"
    },
    {
      "properties": {},
      "type": "object"
    }
  ],
  "type": "array"
}
                    

  • {
  "additionalProperties": {
    "$ref": "https://localhost/ExportDocs#/$defs/Record"
  },
  "propertyNames": {
    "type": "string"
  },
  "type": "object"
}
                    

  • {
  "items": {
    "$ref": "https://localhost/ExportDocs#/$defs/Record"
  },
  "type": "array"
}
                    

  • {
  "properties": {
    "tag_a": {
      "properties": {
        "field_x": {
          "maximum": 255,
          "minimum": 0,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "tag_b": {
      "properties": {
        "field_z": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
                    

  • {
  "enum": [
    "a",
    10,
    true,
    null
  ]
}

Import

JSON Schema (draft 2020-12) to FModel

Purpose of FModel Import is for "getting started" quickly from existing schema. Imported schema is NOT going to be lossless. We expect `draft 2020-12`, but our chosen keywords are likely what you are already using; those stable ones.


Output from FModel to JSON Schema section is expected to be input. If source schema file's `$defs` or `definitions` name has namespace, import will try to group by that namespace, for example, "AWS_ACMPCA_Policy". "AWS_ACMPCA" is going to be module name, "Policy" is going to be one of module's fmodels. By default, imported definitions are grouped by first character.

Keyboard commands

Add

Add random schema to container types
Shift + +

Move

Cut selected schemas
Cmd + x
Copy selected schemas
Cmd + c
Paste
Cmd + v
Cancel copy or cut
Escape

Clone

Clone selected schemas
Shift + Alt + ArrowUp

Shift + Alt + ArrowDown

Reorder

Reorder selected schemas up or down
Alt + ArrowUp

Alt + ArrowDown

Collapse / Expand

Collapse selected schemas
ArrowLeft
Expand selected schemas
ArrowRight

Delete

Delete selected schemas
Delete

Select

Select a schema
ArrowUp
ArrowDown
Select a sibling schema
i
j
Select mutiple schemas
Shift + ArrowUp
Shift + ArrowDown
Select mutiple schema all the way
Shift + Cmd + ArrowUp

Shift + Cmd + ArrowDown
Select the first child
Cmd + ArrowUp
Select the last child
Cmd + ArrowDown
Select the root element of tree
Home
Select the last element of tree
End

Rename key

Enable key editing on a selected schema
Enter
Submit a changed key with current text input value
Enter
Cancel editing
Escape

Change type

Enable type editing on a selected schema
Shift + Enter
Submit a changed type with current text input value
Enter
Cancel editing
Escape
For Windows, use Ctrl in place of Cmd