E
Eamon Mason
Problem Statement
Port's 100-character identifier limit makes it impossible to reliably create unique, deterministic identifiers for documentation entities using natural keys (repository + filepath), which frequently exceed this limit. There is currently no built-in way to generate SHA hashes from property values during entity creation, forcing users to choose between:
  1. Truncated paths → Risk of identifier collisions
  2. Manual hash generation → Inconsistent, error-prone, requires external tooling
  3. Filename-only identifiers → Guaranteed collisions (multiple
    README.md
    files)
Current Constraints
Identifier Limit
  • Maximum identifier length: 100 characters
  • Pattern requirement:
    ^[A-Za-z0-9@_.:\\/=-]+$
Real-World Examples Exceeding Limit
Example 1: GitHub Documentation Path
Repository: tr/platform-engineering-kubernetes-infrastructure
File path: .github/PULL_REQUEST_TEMPLATE/pull_request_template.md
Natural identifier: tr/platform-engineering-kubernetes-infrastructure/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
Character count: 109 characters
Example 2: Deep Documentation Structure
Repository: atpa-gst-ai-assistant
File path: documentation/architecture/backend-services/authentication/oauth-integration-guide.md
Natural identifier: atpa-gst-ai-assistant/documentation/architecture/backend-services/authentication/oauth-integration-guide.md
Character count: 114 characters
Example 3: Long Repository Names
Repository: thomson-reuters-legal-technology-innovation
File path: docs/deployment/kubernetes/production-configuration.md
Natural identifier: thomson-reuters-legal-technology-innovation/docs/deployment/kubernetes/production-configuration.md
Character count: 117 characters
This is critical for us as:
  1. Blocks core functionality: Can't reliably upsert entities
  2. Forces workarounds: External scripting required for all integrations
  3. Data quality issues: Identifier collisions cause data loss
  4. Operational overhead: Manual identifier management doesn't scale
  5. Architecture constraint: Limits usefulness of Port for documentation management