aws-cloudformation / aws-cloudformation/cloudformation-coverage-roadmap

[Resource Type] - [Docs] - Improve documentation clarity for OpenSearchServerless Index Mappings Properties notation

Open
#2,336 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
No language data
Stars
1.1k
Forks
62
PR merge metrics
No merged PRs in 30d

Description

### Name of the resource

Other

### Resource name

AWS::OpenSearchServerless::Index

### Reference Link

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opensearchserverless-index-mappings.html

### Details

## Issue Description
The current documentation for AWS::OpenSearchServerless::Index Mappings Properties is unclear about the required key-value pair notation structure. This makes it difficult for users to understand how to properly format their CloudFormation templates.

## Current Documentation
The current documentation at [AWS::OpenSearchServerless::Index Mappings](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opensearchserverless-index-mappings.html) doesn't provide clear examples of the required structure.

## Example of Invalid Template
```yaml
Mappings:
Properties:
Dimension: 1536
Type: knn_vector
```
## Example of Valid Template
```yaml
Mappings:
Properties:
test: # Required field name
Dimension: 1536
Type: knn_vector
```

## Suggested Improvements
- Add complete working examples to the documentation
- Clarify that a field name is required as a key in the Properties object
- Include more detailed explanation of the structure and its requirements
- Add common use cases and their corresponding template structures
## Impact
### This improvement would help users:
- Avoid trial and error when creating templates
- Better understand the required structure
- Save time in template development
- Reduce support queries related to this issue
-
Would you please consider updating the documentation to make it more clear and user-friendly?

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the AWS::OpenSearchServerless::Index Mappings reference linked in the issue and compare its current notation with the invalid and valid YAML examples provided. Update the documentation with a clear field-name key explanation and complete working examples; done means users can understand and reproduce the required Properties structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, yaml
Domain
cloud, documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.