Skip to main content
A Portal Definition is a graph of JSON resources under portal/. Cross-resource references use file slugs.

​
Resource roles

  • definition.json stores top-level metadata for the Portal Definition.
  • A screen defines a route and contains zero or one root widget node.
  • A navigation orders links to screens for a web or mobile experience.
  • A profile selects navigation and theme resources and can filter access for members.
  • A theme contains a complete structured theme configuration.
Use PortalDefinition and PortalResource for exact fields and accepted values.

​
Use file slugs for references

If a screen is stored at portal/screens/team-dashboard.json, its slug is team-dashboard. Use that slug from navigation resources. Apply the same rule to navigation, profile, and theme references. Renaming a file changes its slug. Update every reference in the same change.

​
Build a valid graph

Before push, verify that:
  • every referenced screen, navigation, profile, and theme exists;
  • each JSON file validates against its declared schema;
  • one intended profile is the default, when the definition has profiles;
  • theme resources contain their complete required configuration;
  • widget nodes match the current widget schema.
An empty definition can have no resource files. Add a complete connected graph before you push a usable portal.

​
Resolve drift before writing

Pull before editing when another author may have changed the remote working definition. If local and remote changes conflict, preserve the local work, pull current state, reapply the intended change, and review the resulting diff.