Proposal: Structured Data Modeling Documentation

[s2-CosmicAlgorithm]

Structured Data Modeling Documentation

PROBLEM

The core problems in projects is the complexity of structured documentation of data models between stakeholders. This effects Business-, Enginnering- and Testing-departments in different points. Documentation for specific needs are created which are incompatible with the other departments, so redundancy and asynchron versions.

PROPOSAL

The solution must be a specification schema. This schema must help to create, update, versionize, and document a structured data model to the need of every department. The schema should include topics like: Data Model (e.g. specifications: mandatory fields, RegEx, ENUMs, defaults, conditional fields, error codes, fieldlength, filetypes, validation APIs), leading systems, data mapping, and test data.

GOALS

The structured documentation out of the generic schema must be easily consumable by every stakeholder within the project. This should close the gap between departments and elevate the implementation between departments and technology / solutions. The schema will be maintained by a schema team. The consumption of the schema should enable the project team to use an interface (which needs to be further elaborated) to specify their data model. And then should be stored in a dedicated project repository, to make it consumable within the whole project.

RESTRICTIONS

None so far.

STAKEHOLDER

• Business / System Architects
• Enginnering (Frontend, Backend, API, Enterprise Systems)
• QA / Testing

AFFECTED PROJECTS

None, so far.

SPECIFICATIONS

The proposal is to generate a generic schema, that can be used to create data models in your projects.

NEXT STEPS

1. Draft a rough first data model schema, to visualize the idea.
2. talk to represenatives of possible stakeholders to collect their feedback on such a model
3. optimize the model to a first ready to use status
4. offer the idea to projects to use this in their project to get real life experience
5. outlook: optimize schema based on the projects usage and requirements

TIMELINE

The first draft of such an approach should be done with a few working days.

[s2-julceb]

@fryday-s2 thanks for the proposal.

In general it sounds like you propose to use something like JSON Schema to document data structures.

What data structures should be documented that way; API responses, component parameters?
If you could provide a few concrete examples it could help to understand the scope of the proposal.
Thank you.

[s2-julceb]

Update: the proposal was accepted and the tool that was created out of it will be released in the next few weeks