@128technology/ply-json

PLY

PLY (Presentation Language for Yinz) is a library to manage JSON files that model a GUI for configuring a YANG (RFC 6020) datastore. It directly integrates with the Yinz library which manages both the datamodel and instance data associated with that datamodel.

PLY intends to provide the following functionality:

• Ingest a presentation model described by one or more JSON files.
• Ingest a datamodel and associate it with the presentation model. The datamodel will be used to look up information from fields.
• Injest an instance of the model and associate the values from the instance with presentation fields.
• Serialize this presentation instance to JSON that can be sent to a client to draw a GUI.
• Validate that a presentation model is both syntactically and semantically valid.
• Given a datamodel, ensure that all aspects of the datamodel have a corresponding entry in the presentation model.

Model Format

Pages

A page is typically broken out into it's own JSON file. Pages generally represent containers and instances of list items. For example, if the model has a list of routers, there would probably be a page named router.json which describes what an instance of a router would look like. The schema of a page is pretty simple, it contains a title, an id, and an array of sections. The most basic page would like like the following:

{
  "id": "my-new-page",
  "title": "My New Page",
  "sections": []
}

Generally it is a good idea for the page id to match the name of the file. For example, router.json would have an id of router.

Sections

leaf-section

If you have a section of basic fields (e.g. no containers, lists, or leaf-lists), then this is the section type you would want to use. This section type has an id, a title, and an array of fields. Generally the id for the section has the format page-id.section-id, so if it was on the router page it might look something like router.settings. If you do not specify a type for a section it will default to this type. A basic leaf-section looks like the following:

{
  "id": "my-new-page.my-new-section",
  "title": "My New Section",
  "fields": []
}

If you chose to specify the type explicitly it would look like:

{
  "id": "my-new-page.my-leaf-section",
  "title": "My Leaf Section",
  "type": "leaf-section",
  "fields": []
}

list-section

All lists need to be contained in their own list-section. A list-section will have exactly one field which references the list itself. A list-section's title field is explicitly set to null and the label of the list field inside the section is used instead. The specifics of the single list field are outlined in the Fields section, including descriptions of the link and columns properties. A basic list-section looks like the following:

{
  "id": "my-new-page.my-list-section",
  "title": null,
  "type": "list-section",
  "fields": [{
    "link": "dog",
    "id": "id.to.a.list",
    "label": "Dogs"
  }]
}

list-table

All leaf-lists need to be contained in their own list-table section. Similarly to the list-section a list-table section has exactly one field describing the leaf-list. It also has a title explicitly set to null. An example list-table section looks like the following:

{
  "id": "my-new-page.my-list-table-section",
  "title": null,
  "type": "list-table",
  "fields": [{
    "id": "id.to.a.leaf-list",
    "label": "Cats",
    "columnLabels": [{
      "id": "name",
      "label": "Cat"
    }]
  }]
}

container-list-section

If you want links that dive into one or more containers/pages in a section, you will want to use the container-list-section. An example looks like the following:

{
  "id": "my-new-page.my-link-section",
  "title": "Example Container Links",
  "type": "container-list-section",
  "fields": [{
    "id": "id.to.a.container",
    "link": "container-1",
    "label": "Container 1"
  }]
}

Fields

leaf

{
  "id": "id.to.a.leaf",
  "label": "My Leaf Field"
}

choice

While a choice field technically has no value in the running config, it will be populated with the cases in the model and the selected case is inferred at runtime.

{
  "id": "id.to.a.choice",
  "label": "My Choice Field"
}

container

Containers do not have to be represented in the presentation model. They should be used in cases where a link to a page representing the container is desired. The link MUST correspond to an id of another page.

{
  "id": "id.to.a.container",
  "label": "My Container Field",
  "link": "page-for-container"
}

leaf-list

The columnLabels property is used to describe a label for the columns of a table displaying the leaf-list. In this case since a leaf-list only has one column, this array should only contain one item. A leaf-list field can only by contained in a list-table section.

{
  "id": "id.to.a.leaf-list",
  "label": "My Leaf List Field",
  "columnLabels": [{
    "id": "thing",
    "label": "thing"
  }]
}

list

The columns property of a list field is optional. It is intended to denote which columns (leafs) should be displayed if the list if presented in a table. Otherwise typically only the key fields would be presented in a table. The link MUST correspond to an id of the page for the list instance. For example if the list field describes the list of all routers, then the link must correspond to the router page describing an individual router. A list field can only by contained in a list-section.

{
 "id": "id.to.a.leaf-list",
 "label": "My List Field",
 "link": "my-list-instance",
 "columns": ["name", "description"]
}