From 3384e3db16f066acdafd644c96d308efdc7be6d1 Mon Sep 17 00:00:00 2001 From: Mads Bolaris Date: Tue, 30 Sep 2025 17:39:27 -0700 Subject: [PATCH 1/5] introduce llm-friendly properties --- schemas/apiDefinition.swagger.schema.json | 68 ++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/schemas/apiDefinition.swagger.schema.json b/schemas/apiDefinition.swagger.schema.json index 2792666d23..2ce7434fc4 100644 --- a/schemas/apiDefinition.swagger.schema.json +++ b/schemas/apiDefinition.swagger.schema.json @@ -366,6 +366,15 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" + }, + "x-ms-search-description": { + "$ref": "#/definitions/x-ms-search-description" } } }, @@ -558,6 +567,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } }, "patternProperties": { @@ -621,6 +636,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } }, "additionalProperties": false @@ -737,7 +758,13 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" - } + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" + }, } }, "queryParameterSubSchema": { @@ -863,6 +890,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } } }, @@ -984,6 +1017,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } } }, @@ -1113,6 +1152,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } } }, @@ -1300,6 +1345,12 @@ }, "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" + }, + "x-ms-llm-name": { + "$ref": "#/definitions/x-ms-llm-name" + }, + "x-ms-llm-description": { + "$ref": "#/definitions/x-ms-llm-description" } }, "additionalProperties": false @@ -2556,6 +2607,21 @@ "internal" ] }, + "x-ms-llm-name": { + "title": "The llm-friendly name for an entity", + "description": "Use snake case and avoid special characters for the best results with llm models.", + "type": "string" + }, + "x-ms-llm-description": { + "title": "The llm-friendly usage description for an entity", + "description": "The description for the entity that explains how the entity is used.", + "type": "string" + }, + "x-ms-search-description": { + "title": "The search-friendly description for an entity; used for indexing and discovery scenarios", + "description": "A short description for the entity that explains how the entity is used. Should include important keywords and scenarios that a user might search for.", + "type": "string" + }, "x-ms-url-encoding": { "title": "Encoding style to use for this parameter", "description": "Identifies if the current path parameter should be double url-encoded `double` or single url-encoded `single`. Absence of this field means `single` encoding.", From 2e682c4105d9e3ee3f7dd75b250cb91dfe8b669e Mon Sep 17 00:00:00 2001 From: Mads Bolaris Date: Mon, 6 Oct 2025 11:24:48 -0700 Subject: [PATCH 2/5] Remove search description property --- schemas/apiDefinition.swagger.schema.json | 8 -------- 1 file changed, 8 deletions(-) diff --git a/schemas/apiDefinition.swagger.schema.json b/schemas/apiDefinition.swagger.schema.json index 2ce7434fc4..be94eeeda2 100644 --- a/schemas/apiDefinition.swagger.schema.json +++ b/schemas/apiDefinition.swagger.schema.json @@ -372,9 +372,6 @@ }, "x-ms-llm-description": { "$ref": "#/definitions/x-ms-llm-description" - }, - "x-ms-search-description": { - "$ref": "#/definitions/x-ms-search-description" } } }, @@ -2617,11 +2614,6 @@ "description": "The description for the entity that explains how the entity is used.", "type": "string" }, - "x-ms-search-description": { - "title": "The search-friendly description for an entity; used for indexing and discovery scenarios", - "description": "A short description for the entity that explains how the entity is used. Should include important keywords and scenarios that a user might search for.", - "type": "string" - }, "x-ms-url-encoding": { "title": "Encoding style to use for this parameter", "description": "Identifies if the current path parameter should be double url-encoded `double` or single url-encoded `single`. Absence of this field means `single` encoding.", From e156dbee4e03b989fab54376c119886071979be8 Mon Sep 17 00:00:00 2001 From: Mads Bolaris Date: Mon, 6 Oct 2025 16:28:09 -0700 Subject: [PATCH 3/5] change to name for agent and description for agent --- schemas/apiDefinition.swagger.schema.json | 68 +++++++++++------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/schemas/apiDefinition.swagger.schema.json b/schemas/apiDefinition.swagger.schema.json index be94eeeda2..ff32b5937a 100644 --- a/schemas/apiDefinition.swagger.schema.json +++ b/schemas/apiDefinition.swagger.schema.json @@ -367,11 +367,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } } }, @@ -565,11 +565,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } }, "patternProperties": { @@ -634,11 +634,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } }, "additionalProperties": false @@ -756,11 +756,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" }, } }, @@ -888,11 +888,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } } }, @@ -1015,11 +1015,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } } }, @@ -1150,11 +1150,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } } }, @@ -1343,11 +1343,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-llm-name": { - "$ref": "#/definitions/x-ms-llm-name" + "x-ms-name-for-agent": { + "$ref": "#/definitions/x-ms-name-for-agent" }, - "x-ms-llm-description": { - "$ref": "#/definitions/x-ms-llm-description" + "x-ms-description-for-agent": { + "$ref": "#/definitions/x-ms-description-for-agent" } }, "additionalProperties": false @@ -2604,12 +2604,12 @@ "internal" ] }, - "x-ms-llm-name": { + "x-ms-name-for-agent": { "title": "The llm-friendly name for an entity", "description": "Use snake case and avoid special characters for the best results with llm models.", "type": "string" }, - "x-ms-llm-description": { + "x-ms-description-for-agent": { "title": "The llm-friendly usage description for an entity", "description": "The description for the entity that explains how the entity is used.", "type": "string" From 49317ec1b84711a2499f480837e7ee9f2207f8a9 Mon Sep 17 00:00:00 2001 From: Mads Bolaris Date: Tue, 7 Oct 2025 21:08:49 -0700 Subject: [PATCH 4/5] for agent to for model --- schemas/apiDefinition.swagger.schema.json | 68 +++++++++++------------ 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/schemas/apiDefinition.swagger.schema.json b/schemas/apiDefinition.swagger.schema.json index ff32b5937a..b60f843aef 100644 --- a/schemas/apiDefinition.swagger.schema.json +++ b/schemas/apiDefinition.swagger.schema.json @@ -367,11 +367,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } } }, @@ -565,11 +565,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } }, "patternProperties": { @@ -634,11 +634,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } }, "additionalProperties": false @@ -756,11 +756,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" }, } }, @@ -888,11 +888,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } } }, @@ -1015,11 +1015,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } } }, @@ -1150,11 +1150,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } } }, @@ -1343,11 +1343,11 @@ "x-ms-visibility": { "$ref": "#/definitions/x-ms-visibility" }, - "x-ms-name-for-agent": { - "$ref": "#/definitions/x-ms-name-for-agent" + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" }, - "x-ms-description-for-agent": { - "$ref": "#/definitions/x-ms-description-for-agent" + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } }, "additionalProperties": false @@ -2604,12 +2604,12 @@ "internal" ] }, - "x-ms-name-for-agent": { + "x-ms-name-for-model": { "title": "The llm-friendly name for an entity", "description": "Use snake case and avoid special characters for the best results with llm models.", "type": "string" }, - "x-ms-description-for-agent": { + "x-ms-description-for-model": { "title": "The llm-friendly usage description for an entity", "description": "The description for the entity that explains how the entity is used.", "type": "string" From 1f9624476a5f678940997b2cff76bfd79ac1678f Mon Sep 17 00:00:00 2001 From: Mads Bolaris Date: Thu, 30 Oct 2025 08:07:48 -0700 Subject: [PATCH 5/5] Add missing name/description for model --- schemas/apiDefinition.swagger.schema.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/schemas/apiDefinition.swagger.schema.json b/schemas/apiDefinition.swagger.schema.json index b60f843aef..6599df976d 100644 --- a/schemas/apiDefinition.swagger.schema.json +++ b/schemas/apiDefinition.swagger.schema.json @@ -1527,6 +1527,12 @@ }, "x-ms-dynamic-tree": { "$ref": "#/definitions/x-ms-dynamic-tree" + }, + "x-ms-name-for-model": { + "$ref": "#/definitions/x-ms-name-for-model" + }, + "x-ms-description-for-model": { + "$ref": "#/definitions/x-ms-description-for-model" } }, "additionalProperties": false