GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Proposal: YAML flow-map properties on typed relationship links
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
## Summary
Extend the typed relationship link conventions discussed in #101, #148, and #183 by allowing an optional YAML flow mapping after `rel:` in a Markdown link title.
```markdown
[Customers](/tables/customers.md "rel:depends_on {confidence: inferred, weight: 0.8}")
```
This represents a Source–Type–Target relationship with zero or more properties while remaining an ordinary Markdown link.
## Proposed syntax
```text
relationship-title = "rel:" relationship-type [SP yaml-flow-mapping]
```
Examples:
```markdown
[Orders](/tables/orders.md "rel:writes_to")
[Orders](/tables/orders.md "rel:writes_to {confidence: inferred}")
[Legacy API](/apis/legacy.md "rel:supersedes {effective_since: '2026-08-01', reason: migration}")
```
Semantics:
- The containing concept is the relationship Source.
- The Markdown destination is the relationship Target.
- The token after `rel:` is the producer-defined Relationship Type.
- The optional YAML flow mapping contains Relationship Properties. These properties belong to the relationship, not to either endpoint.
- Omitting the mapping preserves the existing `rel:` form.
- Property values retain their YAML types.
- The optional value must parse as a mapping, rather than a scalar or sequence.
- Canonical writers should emit standard YAML spacing, for example `{confidence: inferred}`.
- Consumers that do not implement this convention continue to treat the title as opaque link metadata and the link as an ordinary OKF relationship.
Relationship types and property keys remain producer-defined. Consumers should preserve unknown types and properties and ignore those they do not understand.
## Motivation
The existing proposals cover related pieces but do not provide a general inline representation for relationship properties:
- #101 proposes using the Markdown link title for a relationship type and descriptive context.
- #148 proposes typed relationships using either structured frontmatter or an inline `rel:` title.
- #183 proposes `target`, `rel`, and `confidence` in a frontmatter `links:` collection.
- #139 demonstrates another independent relationship property, `level`.
Once producers need both `confidence` and `level`—or fields such as `role`, `weight`, `effective_since`, or `provenance`—adding one dedicated syntax rule per field does not scale. A YAML flow mapping supplies a small, extensible property bag using syntax already familiar to OKF authors.
## Compatibility and round-tripping
This proposal does not introduce new Markdown syntax. It only defines an optional convention inside the standard Markdown link title.
A property-graph consumer can map the example losslessly to a relationship annotation such as:
```markdown
[:DEPENDS_ON {confidence: inferred, weight: 0.8}](/tables/customers.md)
```
Likewise, a structured consumer can project it to a frontmatter representation without inventing field-specific mappings:
```yaml
links:
- target: /tables/customers.md
rel: depends_on
properties:
confidence: inferred
weight: 0.8
```
The inline link should remain the source of truth unless a future OKF convention explicitly defines synchronization with a frontmatter index.
## Open questions
1. Should Relationship Properties allow all YAML values, or only scalar values and scalar sequences?
2. Should duplicate property keys be invalid for deterministic consumption?
3. Should the specification define the normalized `links:` projection shown above, or leave that to producers?
4. Should human-readable context remain a separate link-title suffix, or simply be represented as a property such as `description`?
Contributor guide
Research direction
Start by reviewing the related proposals in #101, #148, #183, and #139, then examine how typed relationship links are currently documented and consumed. Resolve the open questions about YAML value types, duplicate keys, projections, and human-readable context; done means the convention is specified consistently without breaking the existing rel: form.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, yaml
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100