Open-Needs Models#

Open-Needs is written to support docs-as-code philosophy and existing tools. And as most information is stored in files on code versioning systems, also the main source of information for Open-Needs shall be files.

Beside extracting need objects from documentation files (e.g. md or rst), it shall be also possible to import them from json-files, which may contain exported data from an issue tracking systems.

Also the complete configuration of a project in Open-Needs shall be defined in json format and files.

@startuml skinparam nodesep 50 skinparam ranksep 50 card "Organization" as org #6af { card "Project/s" as projects } card "Project" as project #6af{ card "Project Domain" as domain_own card "Domain/s" as domains card "Needs" as pr_needs } rectangle "Domain" as domain #6af card "Needs container" as cont #6af { card "Container\nDomain" as domain2 card "Need/s" as needs } rectangle "Need" as need #6af projects => project : references domains ==> domain : references cont -[hidden]> need @enduml

@startuml skinparam nodesep 50 skinparam ranksep 50 !include models_overview.puml artifact "organization.schema" as s_org #6fa artifact "project.schema" as s_project #6fa artifact "domain.schema" as s_domain #6fa artifact "needs_container.schema" as s_need_cont #6fa artifact "need.schema" as s_need #6fa ''Schema links s_org --> org : describes s_project --> project : describes s_domain --> domain : describes s_domain --> domain2 : describes s_domain --> domain_own : describes s_need_cont --> cont : describes s_need --> needs : describes s_need --> need : describes s_need --> pr_needs : describes @enduml

json-schema#

All kind of data provided by or stored inside Open-Needs shall have a schema defined by json-schema.

This shall affect all Open-Needs related files, which are created/used by client tools. E.g. a project configuration, stored as open_needs_project_conf.json, which is used by a client tool like Sphinx-Needs to setup the project configuration on Open-Needs Server.

json-schema will not be used to validate REST API requests or the content of the database. It is mostly used to validate files, which are used inside a docs-as-code approach to keep information in files and therefore also on git repositories.

Organization configurations#

An organization is an unique entity, which contains mostly projects only.

It may be used in future for common configuration of projects, which belong to one organization.

Schema#

name

Organization schema

uri

https://open-needs.org/organization.schema.json

location

/models/organization.schema.json

status

work in progress

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-needs.org/organization.schema.json",
  "title": "Open-Needs Organization schema",
  "type": "object",
  "properties": {
    "key": {
      "description": "An unique string as key, which represents the organization in urls.",
      "type": "string"
    },
    "title": {
      "description": "A title for the organization, which is used as textual representation in documents and websites.",
      "type": "string"
    },
    "description": {
      "description": "A description of the organization.",
      "type": "string"
    },
    "url": {
      "description": "An url to a webpage of the organization.",
      "type": "string"
    },
    "projects": {
      "description": "A list of projects belonging to the organization",
      "type": "array",
      "items": {
         "$ref": "https://open-needs.org/project.schema.json"
       }
    }
  },
  "required": ["key", "title", "projects"]
}

https://open-needs.org/organization.schema.json

Open-Needs Organization schema

type

object

properties

  • key

An unique string as key, which represents the organization in urls.

type

string

  • title

A title for the organization, which is used as textual representation in documents and websites.

type

string

  • description

A description of the organization.

type

string

  • url

An url to a webpage of the organization.

type

string

  • projects

A list of projects belonging to the organization

type

array

items

https://open-needs.org/project.schema.json

@startjson !include models/organization.schema.json @endjson

Project configurations#

In Open-Needs a project configuration contains the configuration for the following elements:

  • need types

  • need options

  • need link types

  • project warnings

  • global option values

  • and much more

Take a look into the configuration documentation of Sphinx-Needs to get a feeling about what may be part of a project configuration in future.

Most configuration is clustered inside Open-Needs Domains, so that a project configuration contains its project specific config under the domain project and imports the other domains under their domain specific name.

Schema#

name

Project schema

uri

https://open-needs.org/project.schema.json

location

/models/project.schema.json

status

work in progress

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-needs.org/project.schema.json",
  "title": "Open-Needs Project schema",
  "type": "object",
  "properties": {
    "key": {
      "description": "An unique string as key, which represents the project in urls.",
      "type": "string"
    },
    "title": {
      "description": "A title for the project, which is used as textual representation in documents and websites.",
      "type":  "string"
    },
    "description": {
      "description": "A textual description of the project.",
      "type":  "string"
    },
    "url": {
      "description": "An url to a webpage of the project.",
      "type":  "string"
    },
    "configuration": {
      "description": "A project specific configuration, based on domain.schema",
      "$ref": "https://open-needs.org/domain.schema.json"
    },
    "domains": {
      "description": "A list of domains configuring the project",
      "type": "array",
      "items": {
         "$ref": "https://open-needs.org/domain.schema.json"
      }
    },
    "needs": {
      "description": "A list of needs belonging to the project",
      "type": "array",
      "items": {
         "$ref": "https://open-needs.org/need.schema.json"
      }
    }
  },
  "required": ["key", "title", "configuration", "domains", "needs"]
}

https://open-needs.org/project.schema.json

Open-Needs Project schema

type

object

properties

  • key

An unique string as key, which represents the project in urls.

type

string

  • title

A title for the project, which is used as textual representation in documents and websites.

type

string

  • description

A textual description of the project.

type

string

  • url

An url to a webpage of the project.

type

string

  • configuration

A project specific configuration, based on domain.schema

https://open-needs.org/domain.schema.json

  • domains

A list of domains configuring the project

type

array

items

https://open-needs.org/domain.schema.json

  • needs

A list of needs belonging to the project

type

array

items

https://open-needs.org/need.schema.json

@startjson !include models/project.schema.json @endjson

Domain configurations#

Open-Needs Domains are a collection of need types, fields, checks and automatism, which are used to configure a project for one or multiple specific domains.

With using domains a project gains the possibility to create and mange need objects for these domains.

Domains are used to provide a common setup for a specific domain, so that no projects needs define all the needed need types and rules completely from scratch.

Examples for domains are:

  • Software development (E.g. requirements and specification types)

  • Software architecture (E.g. class and component types)

  • Autosar (E.g. SWC and runnable types)

  • Employees (E.g. employee, group and role types)

  • Software processes (E.g. process, step, workflow and artifact types)

Schema#

name

Domain schema

uri

https://open-needs.org/domain.schema.json

location

/models/domain.schema.json

status

work in progress

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-needs.org/domain.schema.json",
  "title": "Open-Needs Domain schema",
  "type": "object",
  "properties": {
    "key": {
      "description": "An unique string as key, which represents the domain worldwide.",
      "type": "string"
    },
    "title": {
      "description": "A title for the domain, which is used as textual representation in documents and websites.",
      "type": "string"
    },
    "description": {
      "description": "A description of the domain.",
      "type": "string"
    },
    "url": {
      "description": "An url to a webpage of the domain.",
      "type": "string"
    },
    "types": {
      "description": "List of need types which are defined by this domain",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "key": {
            "description": "Short key as string of the domain type.",
            "type": "string"
          },
          "title": {
            "description": "Title as string of the domain type.",
            "type": "string"
          },
          "color": {
            "description": "Color in hex of the domain type (for graphical representations)",
            "type": "string",
            "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$"
          },
          "style": {
            "description": "A PlantUML style name of the domain type (e.g. node or card).",
            "type": "string"
          }
        },
        "required": ["key", "title", "color", "style"]
      }
    },
    "options": {
      "description": "List of need options which are defined by this domain.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "Name of the option as string.",
            "type": "string"
          },
          "description": {
            "description": "Description for the option.",
            "type": "string"
          },
          "type": {
            "description": "Name of the options",
            "type": "string",
            "enum": ["string", "number"]
          },
          "default": {
            "description": "Default value of the option, if not set.",
            "type": ["string", "number", "null"]
          }
        },
        "required": ["name", "type", "default"]
      }
    },
    "links": {
      "description": "List of need links which are defined by this domain.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "description": "Name of the link as string.",
            "type": "string"
          },
          "description": {
            "description": "Description for the link.",
            "type": "string"
          },
          "incoming": {
            "description": "Label to use for incoming links.",
            "type": "string"
          },
          "outgoing": {
            "description": "Label to use for outgoing links.",
            "type": "string"
          },
          "allow_dead_links": {
            "description": "Links are allowed to reference not existing needs.",
            "type": "boolean"
          },
          "style": {
            "type": "object",
            "properties": {
              "color": {
                "description": "Color of the link in graphical representations.",
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$"
              },
              "color_part": {
                "description": "Color of the link in graphical representations (to need_parts).",
                "type": "string",
                "pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$"
              },
              "start": {
                "description": "PlantUML link start character (e.g. . or - ).",
                "type": "string"
              },
              "end": {
                "description": "PlantUML link end character (e.g. > or --o ).",
                "type": "string"
              }
            },
            "required": []
          }
        },
        "required": ["name", "incoming", "outgoing"]
      }
    }
  },
  "required": ["key", "title", "description", "types", "options", "links"]
}

https://open-needs.org/domain.schema.json

Open-Needs Domain schema

type

object

properties

  • key

An unique string as key, which represents the domain worldwide.

type

string

  • title

A title for the domain, which is used as textual representation in documents and websites.

type

string

  • description

A description of the domain.

type

string

  • url

An url to a webpage of the domain.

type

string

  • types

List of need types which are defined by this domain

type

array

items

type

object

properties

  • key

Short key as string of the domain type.

type

string

  • title

Title as string of the domain type.

type

string

  • color

Color in hex of the domain type (for graphical representations)

type

string

pattern

^#(?:[0-9a-fA-F]{3}){1,2}$

  • style

A PlantUML style name of the domain type (e.g. node or card).

type

string

  • options

List of need options which are defined by this domain.

type

array

items

type

object

properties

  • name

Name of the option as string.

type

string

  • description

Description for the option.

type

string

  • type

Name of the options

type

string

enum

string, number

  • default

Default value of the option, if not set.

type

string / number / null

  • links

List of need links which are defined by this domain.

type

array

items

type

object

properties

  • name

Name of the link as string.

type

string

  • description

Description for the link.

type

string

  • incoming

Label to use for incoming links.

type

string

  • outgoing

Label to use for outgoing links.

type

string

  • allow_dead_links

Links are allowed to reference not existing needs.

type

boolean

  • style

type

object

properties

  • color

Color of the link in graphical representations.

type

string

pattern

^#(?:[0-9a-fA-F]{3}){1,2}$

  • color_part

Color of the link in graphical representations (to need_parts).

type

string

pattern

^#(?:[0-9a-fA-F]{3}){1,2}$

  • start

PlantUML link start character (e.g. . or - ).

type

string

  • end

PlantUML link end character (e.g. > or –o ).

type

string

@startjson !include models/domain.schema.json @endjson

Need item#

A single need item contains mostly its own data.

All dynamic elements (links, dynamic function) shall be resolved in the context of a specific documentation build/version.

It does not contain any information about project/domain configuration. For this a Needs container must be used.

So it acts mostly as a key-value store.

Schema#

name

Need schema

uri

https://open-needs.org/need.schema.json

location

/models/need.schema.json

status

work in progress

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-needs.org/need.schema.json",
  "title": "Open-Needs Need schema",
  "type": "object",
  "patternProperties": {
    "^.*$": {
      "type": [
        "string",
        "number",
        "null"
      ]
    }
  },
  "required": [
    "id",
    "source_type",
    "source_uri"
  ]
}

https://open-needs.org/need.schema.json

Open-Needs Need schema

type

object

patternProperties

  • ^.*$

type

string / number / null

@startjson !include models/need.schema.json @endjson

Needs container#

Needs can be created/imported via the documentation files or by a needs_container.json file.

A needs container can be used to store data from external systems (like Jira or Codebeamer) and make it available in the docs-as-code environment.

Also the Open-Needs tools are using this format to export their data, so that it can be used by scripts and other tools.

A needs container only contains needs related information, this may be:

  • Needs: All exported needs in a list with their data

  • Needs Domain: needs related project configuration as Open-Needs Domain config (needed types, options)

The exported Domain does contain information about the need configuration only. E.g. what types and options must be configured. It shall not contain none-need specific information like warnings, global values or automatism.

A needs container contains the “executed” information of needs in a specific documentation context/run. All possible dynamic functions and references must be resolved.

Schema#

name

Needs container schema

uri

https://open-needs.org/needs_container.schema.json

location

/models/needs_container.schema.json

status

work in progress

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-needs.org/needs_container.schema.json",
  "title": "Open-Needs Needs container schema",
  "type": "object",
  "properties": {
    "key": {
      "description": "An unique string as key, which represents the project in urls.",
      "type": "string"
    },
    "title": {
      "description": "A title for the project, which is used as textual representation in documents and websites.",
      "type":  "string"
    },
    "description": {
      "description": "A textual description of the project.",
      "type":  "string"
    },
    "needs": {
      "description": "A list of needs belonging to the project",
      "type": "array",
      "items": {
         "$ref": "https://open-needs.org/need.schema.json"
      }
    },
    "configuration": {
      "description": "A needs container specific configuration, based on domain.schema",
      "$ref": "https://open-needs.org/domain.schema.json"
    }
  },
  "required": ["key", "title", "configuration", "needs"]
}

https://open-needs.org/needs_container.schema.json

Open-Needs Needs container schema

type

object

properties

  • key

An unique string as key, which represents the project in urls.

type

string

  • title

A title for the project, which is used as textual representation in documents and websites.

type

string

  • description

A textual description of the project.

type

string

  • needs

A list of needs belonging to the project

type

array

items

https://open-needs.org/need.schema.json

  • configuration

A needs container specific configuration, based on domain.schema

https://open-needs.org/domain.schema.json

@startjson !include models/needs_container.schema.json @endjson

Sphinx-Needs schema#

Here is the current json schema of Sphinx-Needs, which is not so complex but maybe can provide some ideas.

Source: needsfile.json

http://json-schema.org/draft-07/schema#

needs.json schema

type

object

properties

  • created

type

string

  • current_version

type

string

  • project

type

string

  • versions

type

object

patternProperties

  • ^.*$

type

object

properties

  • created

type

string

  • filters

type

object

  • filters_amount

type

number

  • needs

patternProperties

  • ^.*$

type

object

properties

  • title

type

string

  • id

type

string

  • description

type

string

  • needs_amount

type

number

additionalProperties

False

Discussion#

For ideas and discussions going into details, please create a specific ticket on our github project.

For any other short information, feel free to add a comment.