Automatically document entity / relationship schema in j1-integration document

[ndowmon]

Would love to see a ticket in the SDK describing this!

Originally posted by @austinkelleher in #611 (comment)

[ndowmon]

Today, we produce a table like:

Resources	Entity _type	Entity _class
AWS Account	aws_account	Account
AWS EC2 Service	aws_ec2	Service
AWS VPC	aws_vpc	Network

---

Given the following schema:

export const EC2Entities = {
  AWS_VPC: {
    resourceName: 'AWS VPC',
    _type: 'aws_vpc',
    _class: ['Network'],
    schema: {
      additionalProperties: true,
      properties: {
        _type: { const: 'aws_vpc' },
        displayName: { type: 'string' },
        vpcId: { type: 'string' },
        region: { type: 'string' },
        id: { type: 'string' },
        awsAccountId: { type: 'string' },
        CIDR: { type: 'string' },
        webLink: { type: 'string' },
      },
      required: ['vpcId', 'region', 'displayName', 'CIDR', 'webLink', 'name'],
    },
  },
};

How should our docs look?

---

Option 1 - Add properties to ###Entities Table:
(note, we need to ensure that our target rendering system can render multi-line markdown cells using HTML tags...)

Data Model

Entities

The following entities are created:

Resources	Entity _type	Entity _class	Properties
AWS Account	aws_account	Account
AWS EC2 Service	aws_ec2	Service
AWS VPC	aws_vpc	Network	displayName: string! vpcId: string! region: string! id: string awsAccountId: string CIDR: string! weblink: string!

---

Option 2 - Add new section (or new document) with entity properties

Data Model

Entities

The following entities are created:

Resources	Entity _type	Entity _class
AWS AccessAnalyzer Service	aws_accessanalyzer	Service
AWS EC2 Service	aws_ec2	Service
AWS SQS Service	aws_sqs	Service
AWS VPC	aws_vpc	Network
SQS Queue	aws_sqs_queue	Queue

Entity Properties

Entities have the following properties:

aws_vpc

• displayName: string!
• vpcId: string!
• region: string!
• id: string
• awsAccountId: string
• CIDR: string!
• webLink: string!

Relationships

The following relationships are created:

Source Entity _type	Relationship _class	Target Entity _type
aws_account	HAS	aws_ec2
aws_ec2	HAS	aws_vpc
aws_sqs_queue	SENDS	aws_sqs_queue
aws_sqs	HAS	aws_sqs_queue

Mapped Relationships

The following mapped relationships are created:

Source Entity _type	Relationship _class	Target Entity _type	Direction
aws_sqs_queue	ALLOWS	*aws_resource*	REVERSE

[austinkelleher]

We will definitely want to produce new documentation pages for entities and relationships respectively. In fact, we may even want to consider producing a document for each entity and one document for relationships. Some entities have many properties and it would cause super slow rendering in a web app if we produced one massive page. In the case of a document per entity, we could have a "glossary" page that would link out to the respective documents.

[ndowmon]

OK. So maybe each row in the table links to another MD document or something?

[austinkelleher]

@ndowmon Yes. Would be excellent.

[ndowmon]

and once it reaches ZD / vanilla / etc, it all blows up.

[austinkelleher]

@ndowmon Definitely will require some custom instrumentation to support on our publicly facing documentation website, but this is a step in the right direction and will serve as our baseline.

[ndowmon]

Should this auto-documentation automatically pull any schemas from the data-model project?

My hunch is no. We should strongly encourage that developers enumerate every property they're adding to this entity, even if it is already enforced by the data model.