Revising M Spec to Reflect Structured Error Messages #391
Conversation
|
@bgribaudo : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change. |
|
Learn Build status updates of commit 7004be1:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| query-languages/m/m-spec-error-handling.md | Details |
query-languages/m/m-spec-error-handling.md
- Line 5, Column 10: [Warning: ms-date-invalid - See documentation]
Invalid date format for 'ms.date': '1/29/26'. If specified, must be a date in format M/D/YYYY, no more than 30 days from today. If you don't specify ms.date, the date will be updated automatically.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
|
Learn Build status updates of commit 20fa09e: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Can you review the proposed changes? Important: When the changes are ready for publication, adding a #label:"aq-pr-triaged" |
prmerger-automator
bot
added
the
aq-pr-triaged
There was a problem hiding this comment.
Pull request overview
This PR updates the M Language specification for error handling to reflect structured error messages that were introduced in recent revisions. The changes document the new error value structure with support for message templates and string interpolation.
Changes:
- Added documentation for the canonical error value record structure including new fields:
ErrorCode,Message.Format, andMessage.Parameters - Documented string interpolation syntax using
#{x}placeholders inMessage.Format - Removed reliance on the
Error.Recordfunction for defining error structure, instead directly specifying the expected record format - Updated documentation date to reflect changes
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| All of the above record fields are optional, and so may be omitted or set to null. When not null, _Reason_, _Message_, and _Message.Format_ must be text, and _Message.Parameters_ must be a list. | ||
|
|
||
| Any additional fields included in the record will be ignored and so not included in the error that is raised. | ||
|
|
||
| _Message.Format_ may contain string interpolation placeholders in the form of `#{x}`, where `x` is a zero-based index. When an error is raised with a non-null _Message.Foramt_, interpolation will be performed using _Message.Format_ as the format string and _Message.Parameters_ as the values to be positionally applied. The resulting output will become the raised error's _Message_. |
There was a problem hiding this comment.
The documentation specifies type constraints for Reason, Message, and Message.Format (must be text when not null) and for Message.Parameters (must be a list when not null), but it does not specify what type ErrorCode and Detail should be when not null. Based on the Error.Record function documentation, ErrorCode should be text, and Detail can be any type. Consider adding this information for completeness.
| All of the above record fields are optional, and so may be omitted or set to null. When not null, _Reason_, _Message_, and _Message.Format_ must be text, and _Message.Parameters_ must be a list. | |
| Any additional fields included in the record will be ignored and so not included in the error that is raised. | |
| _Message.Format_ may contain string interpolation placeholders in the form of `#{x}`, where `x` is a zero-based index. When an error is raised with a non-null _Message.Foramt_, interpolation will be performed using _Message.Format_ as the format string and _Message.Parameters_ as the values to be positionally applied. The resulting output will become the raised error's _Message_. | |
| All of the above record fields are optional, and so may be omitted or set to null. When not null, _ErrorCode_, _Reason_, _Message_, and _Message.Format_ must be text, _Message.Parameters_ must be a list, and _Detail_ may be any value. | |
| Any additional fields included in the record will be ignored and so not included in the error that is raised. | |
| _Message.Format_ may contain string interpolation placeholders in the form of `#{x}`, where `x` is a zero-based index. When an error is raised with a non-null _Message.Format_, interpolation will be performed using _Message.Format_ as the format string and _Message.Parameters_ as the values to be positionally applied. The resulting output will become the raised error's _Message_. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit d483653: ✅ Validation status: passed
For more details, please refer to the build report. |
…docs into error-revisions
|
Learn Build status updates of commit 0745bfb: ✅ Validation status: passed
For more details, please refer to the build report. |
|
If the changes are ready for publication, adding a |
5 participants
M was revised a while back to support structured error messages (e.g. error messages defined as a template + parameters for string interpolation). Also, an error code field has been added to errors in the (somewhat?) recent past.
This edit revises the spec. to reflect these changes. It also changes how defining an error is presented by directly stating the expected record structure, removing the use of/reliance on standard library function
Error.Record.