Adding descriptions to entities and their elements...

[esobrino]

Great Stuff!

Are there plans to allow for assigning descriptions to entities and their elements in the config-file?

Or provide alternatives (if any) to add those,

Eduardo

[seantleonard]

Hi @esobrino, we are tracking this ask with #1682 .

[esobrino]

Sean... I ask about descriptions, and I see another question posted asking for exactly the same and you provided a different answer. I have created some API's with a few hundred of entities and each with their child elements, still not being able to describe those is a problem. I think that an Enterprise level API must include those, my question is if this will be added when?

Again, good stuff hope to see more coming...

[seantleonard]

Hi @esobrino,

The answer I provided here #1619 (comment) is still applicable.
I don't have a date to provide at the moment.

Since table columns (fields in DAB) are resolved at runtime and not defined explicitly in the DAB runtime config, there wouldn't be a way to add a description for those. How do you envision providing descriptions for fields?

This wouldn't be a problem for entities since they are explicitly defined in the runtime config and as part of implementing this ask, we'd just add the ability to provide a description.

[esobrino]

I apologize in advance for the lengthy posting. DAB is good stuff, and I will advocate for its adoption when is appropriate.

JUSTIFICATION

There are too many developed data artifacts in where the documentation is the last thought or a thought at all and therefore when exposing an API I like to have the option to fully document every single entity and related properties (including parameters or others).

(POSSIBLE) RESOLUTION

To provide a resolution for the need of documentation a possibility is to add necessary definitions into the API schema and as an example of such an alternative is described ahead. While using DAB in my scenarios I took the DAB API (v0.8.52) schema (that uses draft-07) and created a kind of an alternative schema rewriting the schema as “draft-04” instead so I can use other tools that don’t manage some of the “draft-07” schema constructs as expected.

One of the prominent differences is that I broke-down as much of the “properties” into distinct types (definitions) so those could be reused instead of having copies of definitions all around. I only mentioned this since the schema that I am attaching describe the DAB API config file in its entirety (so far it does) without using “draft-07” constructs (like “if-then…” stuff) for the purpose of validation. This alternative is friendly to other tools that only support JSON “draft-04” schemas.

Finally, and to provide the mentioned alternative I added a new type (definition) called “documentation”, details about it follows.

API SHEMA ARTIFACTS DOCUMENTATION

Not to collide with other uses of “description” in a schema, a possibility is to have a distinct API schema definition that represent an instance (a sort of) documentation item, for the purpose of discussion let’s say it may be something like:

"documentation_": { 
   "type": "object",
   "properties": {
      "source": {
         "type": "string",
         "description": "Origin from where the documentation came from"
      },
      "language": {
         "type": "string",
         "description": "The language of the body"
      },
      "body": {
         "type": "string",
         "description": "Text body, narrative, definition, or other"
      }
   }
}

DOCUMENTING ENTITIES

As a minimum an “Entity” could be extended (using the DAB-API (draft-04) as follows:

"entity_": {
    "type": "object",
    "properties": {
        "source": {
           "type": "object",
           "description": "The object in the backend database that is mapped to the entity; or entityItem_"
        },
        "rest": {
            "type": "object",
            "description": "restProperties_ or boolean"
        },
        "graphql": {
            "type": "object",
            "description": "graphqlProperties_ or boolean"
        },
        "mappings": {
            "$ref": "#/definitions/mappings_"
        },
        "relationships": {
            "$ref": "#/definitions/relationshipsMap_"
        },
        "permissions": {
            "$ref": "#/definitions/permissions_"
        },
        **"documentation": {
            "$ref": "#/definitions/documentation_"
        }**
    },
    "required": [
       "source",
       "permissions"
    ]
}

The previous takes care of documenting the “entities”, related entity properties (attributes or params) documentation handling follows.

DOCUMENTING ENTITY PROPERTIES – PARAMETERS – OTHER ITEMS

For the documentation of a “Table” entity “Column” or “stored-procedure” entity “Parameter” I created the following alternative:

"propertyInfoMap_": {
   "type": "object",
   "Properties": {
      "value": {
         "type": "object"
      }
      "documentation": {
         "$ref": "#/definitions/documentation_"
      }
   },
   "additionalProperties": {
      "type": "object"
   }
}

As you will see in the attached schema the “entitySourceParameterMap_” could be a value or an instance of “propertyInfoMap_” allowing the documentation of the parameter an/or its value.

To allow for the documentation of entity properties consider:

"entity_": {
    "type": "object",
    "properties": {
        "source": {
           "type": "object",
           "description": "The object in the backend database that is mapped to the entity; or entityItem_"
        },
        "rest": {
            "type": "object",
            "description": "restProperties_ or boolean"
        },
        "graphql": {
            "type": "object",
            "description": "graphqlProperties_ or boolean"
        },
        "mappings": {
            "$ref": "#/definitions/mappings_"
        },
        "relationships": {
            "$ref": "#/definitions/relationshipsMap_"
        },
        "permissions": {
            "$ref": "#/definitions/permissions_"
        },
        **"properties": {
            "$ref": "#/definitions/propertyInfoMap_"
        },**
        "documentation": {
            "$ref": "#/definitions/documentation_"
        }
    },
    "required": [
       "source",
       "permissions"
    ]
}

The previous will allow the description of the properties, its (default) value (if any), and documentation.

CONCLUSIONS

Whatever could be done to offer an alternative to document the entities, properties, parameters of other will definitively contribute to the possibility for the developers/architects to do a better job for their costumers meaning “documenting”.

Please allow us to do a better job and provide documentation.

dab.schema.jsd.json

[esobrino]

The use of "**" was intended to mark the item not part of the code.

[datovy-edam]

Greetings ... dab version 0.10.23

I reviewed the v0.10.23 and tested and it works file, but I still don't see any way to specify a description for Entity - Object - Description. As stated before, I am very happy with dab so far. Adding comments is fundamental for enterprise grade API's. If this is possible within v0.10.23 let me know since I don't see how. If not, please consider adding this that should had been available from day one.

Hope to see dab continue to improve,

Eduardo