GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Proposal: YAML flow-map properties on typed relationship links

Open
#322 2 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.