Skip to content

Commit

Permalink
Add details and add to nav
Browse files Browse the repository at this point in the history
  • Loading branch information
@sblausten
sblausten committed Aug 15, 2024
1 parent 7765658 commit fe92bf5
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 15 deletions.
31 changes: 17 additions & 14 deletions content/docs/catalog/modelling-entities/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ publishedDate: '2024-08-14T14:49:47.0Z'
description: How to model your organisation in the Catalog
---

Your organisation can be modeled in Roadie's Catalog using a variety of different top level `Kinds` which are intended to be broad buckets, combined with a `spec.type` field that can be used to more precisely describe the category.
### Kinds
Your organisation can be modeled in Roadie's Catalog using a variety of different top level `Kinds` which are intended to be broad buckets

For instance the `Component` Kind could have a type of `website` or `internal-tooling` or `external-library` to describe a wide variety of software types and contexts.
Backstage docs explaining the schema approach can be found [here](https://backstage.io/docs/features/software-catalog/system-model/#core-entities).

### Types
Kinds are combined with a `spec.type` field that can be used to more precisely describe the category. For instance the `Component` Kind could have a type of `website` or `internal-tooling` or `external-library` to describe a wide variety of software types and contexts.

Similarly, it is common for organisations to have multiple logical groupings at higher levels like `System` and `Domain` such as "Bounded Context" or "Value Stream". These can also be modeled using `spec.type` and then displayed in their own tab on the Catalog page using our custom Catalog Tab editor.

Expand All @@ -16,20 +20,19 @@ The `spec.type` field is not constrained - you can add anything you like, but it
- Agree a limited set of types for each Kind and encourage care/consensus in adding new ones (having too many, overly specific types can make them less useful sometimes as it can become harder to find things)
- Clean up duplicates with different formating regularly by checking available select options for the type filter on Catalog pages


### Available Kinds

| Kind | Spec Fields (* required) | Available `spec` Relationships |
|-----------|------------------------------|----------------------------------------------------------------------------------------------|
| Component | type*,lifecycle* | owner*,system,dependsOn,dependencyOf,providesApis,consumesApis,subcomponentOf,hasPart,partOf |
| Resource | type* | owner*,system,dependsOn,dependencyOf,hasPart,partOf |
| API | type*,lifecycle*,definition* | owner*,system,dependsOn,dependencyOf,partOf |
| Template | type*,parameters,steps | owner |
| System | type | owner,domain,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| Domain | type | owner,subdomainOf,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| Product | type | owner,system,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| User | profile | memberOf*,managedBy,manages |
| Group | type*,profile | members,managedBy,children*,parent |
| Kind | [Metadata Fields](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-the-metadata) (* required) | [Spec Fields](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) (* required) | Available `spec` Relationships |
|-----------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| Component | name*,namespace,title,description,annotations,labels,tags,links | type*,lifecycle* | owner*,system,dependsOn,dependencyOf,providesApis,consumesApis,subcomponentOf,hasPart,partOf |
| Resource | "" | type* | owner*,system,dependsOn,dependencyOf,hasPart,partOf |
| API | "" | type*,lifecycle*,definition* | owner*,system,dependsOn,dependencyOf,partOf |
| Template | "" | type*,parameters,steps | owner |
| System | "" | type | owner,domain,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| Domain | "" | type | owner,subdomainOf,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| Product | "" | type | owner,system,dependsOn,dependencyOf,parentOf,childOf,hasPart,partOf |
| User | "" | profile | memberOf*,managedBy,manages |
| Group | "" | type*,profile | members,managedBy,children*,parent |

More information on relationships can be found [here](../showing-dependencies)

Expand Down
2 changes: 1 addition & 1 deletion content/docs/catalog/validator/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ validator:
```
## Schemas
The validator is based on the published [Backstage schemas](https://backstage.io/docs/features/software-catalog/descriptor-format) which can be referred to in the Backstage docs.
The validator is based on the published [Backstage schemas](https://backstage.io/docs/features/software-catalog/descriptor-format) which can be referred to in the Backstage docs along with two additional Kinds - [Repository](../repositories) and Product. A list of Kinds available in Roadie can be [found here](../modelling-entities).
## Further reading
Expand Down
1 change: 1 addition & 0 deletions content/docs/docs-nav.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,7 @@ nav:
- Catalog:
- Managing locations: '/docs/catalog/location-management/'
- Rich team pages: '/docs/catalog/rich-team-pages/'
- Modeling entities: '/docs/catalog/modelling-entities/'
- Modeling dependencies: '/docs/catalog/showing-dependencies/'
- Decorating components: '/docs/catalog/decorating-components/'
- Removing components: '/docs/catalog/unregister-components/'
Expand Down

0 comments on commit fe92bf5

Please sign in to comment.