apache / apache/ossie

does ai_context really nessary? Strengthen description and name to reduce reliance on ai_context

Open
#234 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
2.1k
Forks
267
Avg merge
4d 20h
Merged PRs (30d)
24

Description

`A good semantic should describe by itself. `

I'd like to discuss whether ai_context could eventually become optional by making our core metadata more self-descriptive.

### Current situation
ai_context is a pragmatic field today – it provides synonyms, custom instructions, and extra hints for AI tools. I understand its value, but I believe a well-designed semantic model should carry enough meaning in name and description alone.

### Suggestions for stronger naming & descriptions

_Naming conventions:_

- Use business terms (e.g., Revenue not TotalSalesAmount).

- Avoid abbreviations except common ones (e.g., ID).

- Be consistent: use _date suffixes, is_ prefixes for booleans.

- Name the business concept, not its implementation.

- Use singular for models, plural for datasets.

_Descriptions should cover:_

- Grain (what each row represents)

- Source

- Business definition / formula

- Differences from similar fields

- Edge cases or filters

- Synonyms/aliases (which alone can replace many uses of ai_context)

### Conclusion
If we invest in precise, structured descriptions and clear naming, we can significantly reduce the need for ai_context. I'd suggest we treat this as a long‑term goal – perhaps documenting best practices and eventually deprecating ai_context when the metadata is rich enough.

Contributor guide

Open the contributing guide

Research direction

The issue names no files, tests, or entry points; start by reviewing the current semantic metadata model and the ai_context field. Compare the proposed naming and description guidance with existing metadata. Done requires an agreed scope for stronger metadata, documentation of the conventions, and a decision on whether ai_context should eventually be optional or deprecated.

Written by the indexing model from the issue text.

Assessment

Domain
data, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.