From 1bfefe8b2d35732c4b7d6f548a24376722deb34b Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 6 Aug 2021 00:04:54 -0700 Subject: [PATCH 01/51] Introduce first iteration of Android backend API. This includes the initial proto definitions for v1 of Oppia backend's proto-based API. v1 only includes Android support. --- BUILD | 36 ++ WORKSPACE | 60 ++++ proto/BUILD | 3 + proto/v1/BUILD | 3 + proto/v1/api/BUILD | 26 ++ proto/v1/api/android.proto | 113 ++++++ proto/v1/structure/BUILD | 35 ++ proto/v1/structure/concept_card.proto | 28 ++ proto/v1/structure/exploration.proto | 21 ++ proto/v1/structure/image.proto | 21 ++ proto/v1/structure/languages.proto | 86 +++++ proto/v1/structure/objects.proto | 60 ++++ proto/v1/structure/question.proto | 20 ++ proto/v1/structure/revision_card.proto | 28 ++ proto/v1/structure/state.proto | 455 +++++++++++++++++++++++++ proto/v1/structure/topic_summary.proto | 58 ++++ proto/v1/structure/versions.proto | 39 +++ 17 files changed, 1092 insertions(+) create mode 100644 BUILD create mode 100644 WORKSPACE create mode 100644 proto/BUILD create mode 100644 proto/v1/BUILD create mode 100644 proto/v1/api/BUILD create mode 100644 proto/v1/api/android.proto create mode 100644 proto/v1/structure/BUILD create mode 100644 proto/v1/structure/concept_card.proto create mode 100644 proto/v1/structure/exploration.proto create mode 100644 proto/v1/structure/image.proto create mode 100644 proto/v1/structure/languages.proto create mode 100644 proto/v1/structure/objects.proto create mode 100644 proto/v1/structure/question.proto create mode 100644 proto/v1/structure/revision_card.proto create mode 100644 proto/v1/structure/state.proto create mode 100644 proto/v1/structure/topic_summary.proto create mode 100644 proto/v1/structure/versions.proto diff --git a/BUILD b/BUILD new file mode 100644 index 0000000..8dbc40f --- /dev/null +++ b/BUILD @@ -0,0 +1,36 @@ +""" +TODO: fill in +""" + +package_group( + name = "api_visibility", + packages = [ + "//", + ], +) + +package_group( + name = "proto_impl_visibility", + packages = [ + "//proto/...", + ], +) + +java_library( + name = "android_java_protos", + visibility = ["//visibility:public"], + exports = [ + "//proto/v1/api:android_java_proto", + "//proto/v1/structure:structure_java_proto", + ], +) + + +java_library( + name = "android_java_lite_protos", + visibility = ["//visibility:public"], + exports = [ + "//proto/v1/api:android_java_proto_lite", + "//proto/v1/structure:structure_java_proto_lite", + ], +) diff --git a/WORKSPACE b/WORKSPACE new file mode 100644 index 0000000..8b3fff8 --- /dev/null +++ b/WORKSPACE @@ -0,0 +1,60 @@ +""" +TODO: fill in +""" + +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +# Set up Python (as a prerequisite dependency for Protobuf). + +PYTHON_SHA256_HASH = "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b" +PYTHON_VERSION = "0.3.0" + +http_archive( + name = "rules_python", + url = "https://github.com/bazelbuild/rules_python/releases/download/{0}/rules_python-{0}.tar.gz".format(PYTHON_VERSION), + sha256 = PYTHON_SHA256_HASH, +) + +# Set up proto & its toolchain. + +PROTOBUF_SHA256_HASH = "c6003e1d2e7fefa78a3039f19f383b4f3a61e81be8c19356f85b6461998ad3db" +PROTOBUF_VERSION = "3.17.3" + +http_archive( + name = "com_google_protobuf", + sha256 = PROTOBUF_SHA256_HASH, + strip_prefix = "protobuf-%s" % PROTOBUF_VERSION, + urls = ["https://github.com/protocolbuffers/protobuf/archive/v%s.tar.gz" % PROTOBUF_VERSION] +) + +# Set up rules_proto to allow defining proto libraries. + +# Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a +# specific commit hash. +RULES_PROTO_VERSION = "97d8af4dc474595af3900dd85cb3a29ad28cc313" +RULES_PROTO_SHA256_HASH = "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208" + +http_archive( + name = "rules_proto", + sha256 = RULES_PROTO_SHA256_HASH, + strip_prefix = "rules_proto-%s" % RULES_PROTO_VERSION, + urls = ["https://github.com/bazelbuild/rules_proto/archive/%s.tar.gz" % RULES_PROTO_VERSION], +) + +load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") +rules_proto_dependencies() +rules_proto_toolchains() + +# Set up rules_java to enable the Java proto & Java proto lite rules. +RULES_JAVA_VERSION = "0.1.1" +RULES_JAVA_SHA256_HASH = "220b87d8cfabd22d1c6d8e3cdb4249abd4c93dcc152e0667db061fb1b957ee68" + +http_archive( + name = "rules_java", + sha256 = RULES_JAVA_SHA256_HASH, + url = "https://github.com/bazelbuild/rules_java/releases/download/{0}/rules_java-{0}.tar.gz".format(RULES_JAVA_VERSION), +) + +load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") +rules_java_dependencies() +rules_java_toolchains() diff --git a/proto/BUILD b/proto/BUILD new file mode 100644 index 0000000..d0f4e48 --- /dev/null +++ b/proto/BUILD @@ -0,0 +1,3 @@ +""" +TODO: fill in +""" diff --git a/proto/v1/BUILD b/proto/v1/BUILD new file mode 100644 index 0000000..d0f4e48 --- /dev/null +++ b/proto/v1/BUILD @@ -0,0 +1,3 @@ +""" +TODO: fill in +""" diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD new file mode 100644 index 0000000..5c66232 --- /dev/null +++ b/proto/v1/api/BUILD @@ -0,0 +1,26 @@ +""" +TODO: fill in +""" + +load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") +load("@rules_proto//proto:defs.bzl", "proto_library") + +proto_library( + name = "android_proto", + srcs = ["android.proto"], + deps = [ + "//proto/v1/structure:structure_proto" + ], +) + +java_proto_library( + name = "android_java_proto", + visibility = ["//:api_visibility"], + deps = [":android_proto"], +) + +java_lite_proto_library( + name = "android_java_proto_lite", + visibility = ["//:api_visibility"], + deps = [":android_proto"], +) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto new file mode 100644 index 0000000..8b0256a --- /dev/null +++ b/proto/v1/api/android.proto @@ -0,0 +1,113 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.api; + +import "proto/v1/structure/concept_card.proto"; +import "proto/v1/structure/exploration.proto"; +import "proto/v1/structure/question.proto"; +import "proto/v1/structure/revision_card.proto"; +import "proto/v1/structure/topic_summary.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.api"; +option java_multiple_files = true; + +message TopicListRequest { + TopicListRequestResponseStructureVersion structure_version = 1; + + ClientContext client_context = 2; + ClientCompatibilityContext compatibility_context = 3; + ClientDownloadStateContext download_context = 4; +} + +message TopicListResponse { + TopicListRequestResponseStructureVersion structure_version = 1; + + // All topic summaries that are newer & compatible with the client. + repeated org.oppia.proto.v1.structure.TopicSummary topic_summaries = 2; +} + +message TopicContentRequest { + TopicContentRequestResponseStructureVersion structure_version = 1; + + ClientContext client_context = 2; + repeated DownloadRequestStructureIdentifier identifiers = 3; + int32 requested_max_payload_size = 4; +} + +message TopicContentResponse { + TopicContentRequestResponseStructureVersion structure_version = 1; + + repeated StructureDownloadResult download_results = 2; + + // Structure corresponds to TopicContentRequestResponseStructureVersion. + message StructureDownloadResult { + DownloadRequestStructureIdentifier identifier = 1; + + oneof structure_type { + bool skipped_suggest_retry = 2; + org.oppia.proto.v1.structure.RevisionCard revision_card = 3; + org.oppia.proto.v1.structure.ConceptCard concept_card = 4; + org.oppia.proto.v1.structure.Exploration exploration = 5; + QuestionIdList question_id_list = 6; + org.oppia.proto.v1.structure.Question question = 7; + } + } + + // Structure corresponds to TopicContentRequestResponseStructureVersion. + message QuestionIdList { + repeated string question_ids = 1; + } +} + +message ClientContext { + string version_name = 1; + int64 version_code = 2; +} + +message ClientCompatibilityContext { + org.oppia.proto.v1.structure.TopicSummaryStructureVersion topic_summary_structure_version = 1; + org.oppia.proto.v1.structure.RevisionCardStructureVersion revision_card_structure_version = 3; + org.oppia.proto.v1.structure.ConceptCardStructureVersion concept_card_structure_version = 4; + org.oppia.proto.v1.structure.ExplorationStructureVersion exploration_structure_version = 5; + org.oppia.proto.v1.structure.QuestionStructureVersion question_structure_version = 6; + org.oppia.proto.v1.structure.StateStructureVersion state_structure_version = 7; + org.oppia.proto.v1.structure.LanguageStructuresVersion language_structures_version = 8; + org.oppia.proto.v1.structure.ImageStructureVersion thumbnail_structure_version = 9; +} + +message ClientDownloadStateContext { + message DownloadState { + int32 model_version = 1; + oneof structure_type { + string topic_id = 2; // in summary + org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; // in summary + string concept_card_id = 4; + string story_id = 5; // in summary + string exploration_id = 6; // in summary + string question_id = 7; + string skill_id = 8; + } + } + + repeated DownloadState current_downloads = 1; +} + +// This structure's version corresponds to TopicContentRequestResponseStructureVersion. +message DownloadRequestStructureIdentifier { + oneof structure_type { + org.oppia.proto.v1.structure.SubtopicId revision_card_id = 1; + string concept_card_id = 2; + string exploration_id = 3; + string question_list_skill_id = 4; + string question_id = 5; + } +} + +message TopicListRequestResponseStructureVersion { + int32 version = 1; +} + +message TopicContentRequestResponseStructureVersion { + int32 version = 1; +} diff --git a/proto/v1/structure/BUILD b/proto/v1/structure/BUILD new file mode 100644 index 0000000..fb61c62 --- /dev/null +++ b/proto/v1/structure/BUILD @@ -0,0 +1,35 @@ +""" +TODO: fill in +""" + +load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") +load("@rules_proto//proto:defs.bzl", "proto_library") + +proto_library( + name = "structure_proto", + srcs = [ + "concept_card.proto", + "exploration.proto", + "image.proto", + "languages.proto", + "objects.proto", + "question.proto", + "revision_card.proto", + "state.proto", + "topic_summary.proto", + "versions.proto", + ], + visibility = ["//:proto_impl_visibility"], +) + +java_proto_library( + name = "structure_java_proto", + visibility = ["//:api_visibility"], + deps = [":structure_proto"], +) + +java_lite_proto_library( + name = "structure_java_proto_lite", + visibility = ["//:api_visibility"], + deps = [":structure_proto"], +) diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto new file mode 100644 index 0000000..c0a7af2 --- /dev/null +++ b/proto/v1/structure/concept_card.proto @@ -0,0 +1,28 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/image.proto"; +import "proto/v1/structure/languages.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message ConceptCard { + ConceptCardStructureVersion structure_version = 1; + + string skill_id = 2; + string description = 3; + SubtitledHtml explanation = 4; + repeated WorkedExample worked_examples = 5; + RecordedVoiceovers recorded_voiceovers = 6; + WrittenTranslations written_translations = 7; + ReferencedImageList referenced_image_list = 8; + + // Structure version corresponds to ConceptCardStructureVersion. + message WorkedExample { + SubtitledHtml question = 1; + SubtitledHtml explanation = 2; + } +} diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto new file mode 100644 index 0000000..1d47045 --- /dev/null +++ b/proto/v1/structure/exploration.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/image.proto"; +import "proto/v1/structure/state.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message Exploration { + ExplorationStructureVersion structure_version = 1; + + string id = 2; + string title = 3; + string init_state_name = 4; + map states = 5; + int32 model_version = 6; + ReferencedImageList referenced_image_list = 7; +} diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto new file mode 100644 index 0000000..8327b7e --- /dev/null +++ b/proto/v1/structure/image.proto @@ -0,0 +1,21 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message Thumbnail { + ImageStructureVersion structure_version = 1; + + string filename = 2; + int32 background_color_rgb = 3; +} + +message ReferencedImageList { + ImageStructureVersion structure_version = 1; + + repeated string referenced_image_filenames = 2; +} diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto new file mode 100644 index 0000000..1b4da0d --- /dev/null +++ b/proto/v1/structure/languages.proto @@ -0,0 +1,86 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +// Structure corresponds to LanguageStructuresVersion. +enum LanguageCode { + LANGUAGE_CODE_UNSPECIFIED = 0; + ENGLISH = 1; + ARABIC = 2; + HINDI = 3; + HINGLISH = 4; +} + +message SubtitledHtml { + LanguageStructuresVersion structure_version = 1; + + string content_id = 2; + string html = 3; +} + +message RecordedVoiceovers { + LanguageStructuresVersion structure_version = 1; + + repeated VoiceoverContentMapping voiceover_language_mapping = 2; +} + +// Structure corresponds to LanguageStructuresVersion. +message VoiceoverContentMapping { + LanguageCode language_code = 1; + map voiceover_content_mapping = 2; +} + +// Structure corresponds to LanguageStructuresVersion. +message Voiceover { + string filename = 1; + int32 file_size_bytes = 2; + reserved 3; // needs_update + float duration_secs = 4; +} + +message WrittenTranslations { + LanguageStructuresVersion structure_version = 1; + + repeated WrittenTranslationContentMapping translation_language_mapping = 2; +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslationContentMapping { + LanguageCode language_code = 1; + map translation_content_mapping = 2; +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslation { + oneof data_format { + WrittenTranslatableHtml translatable_html = 1; + WrittenTranslatableUnicode translatable_unicode = 2; + WrittenTranslatableSetOfNormalizedString translatable_set_of_normalized_string = 3; + WrittenTranslatableSetOfUnicodeString translatable_set_of_unicode_string = 4; + } +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslatableHtml { + string translation_html = 1; +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslatableUnicode { + string translation_unicode = 1; +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslatableSetOfNormalizedString { + repeated string translations = 1; +} + +// Structure corresponds to LanguageStructuresVersion. +message WrittenTranslatableSetOfUnicodeString { + repeated string unicode_translations = 1; +} diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto new file mode 100644 index 0000000..efdf64c --- /dev/null +++ b/proto/v1/structure/objects.proto @@ -0,0 +1,60 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message Fraction { + bool is_negative = 1; + uint32 whole_number = 2; + uint32 numerator = 3; + int32 denominator = 4; +} + +message TranslatableHtmlContentId { + string content_id = 1; +} + +message SetOfTranslatableHtmlContentIds { + repeated TranslatableHtmlContentId content_ids = 1; +} + +message ListOfSetsOfTranslatableHtmlContentIds { + repeated SetOfTranslatableHtmlContentIds content_id_lists = 1; +} + +message Point2d { + double x = 1; + double y = 2; +} + +message ClickOnImage { + Point2d click_position = 1; + repeated string clicked_regions = 2; +} + +message RatioExpression { + repeated uint32 components = 1; +} + +message TranslatableSetOfNormalizedString { + string content_id = 1; + repeated string normalized_strings = 2; +} + +message ImageWithRegions { + string image_file_path = 1; + repeated LabeledRegion labeled_regions = 2; + + message LabeledRegion { + string label = 3; + oneof region_type { + NormalizedRectangle2d normalized_rectangle_2d = 1; + } + message NormalizedRectangle2d { + Point2d upper_left = 1; + Point2d lower_right = 2; + } + } +} diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto new file mode 100644 index 0000000..ed26281 --- /dev/null +++ b/proto/v1/structure/question.proto @@ -0,0 +1,20 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/image.proto"; +import "proto/v1/structure/state.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message Question { + QuestionStructureVersion structure_version = 1; + + string id = 2; + State question_state = 3; + repeated string linked_skill_ids = 4; + int32 model_version = 5; + ReferencedImageList referenced_image_list = 6; +} diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto new file mode 100644 index 0000000..a5dccde --- /dev/null +++ b/proto/v1/structure/revision_card.proto @@ -0,0 +1,28 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/image.proto"; +import "proto/v1/structure/languages.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message RevisionCard { + RevisionCardStructureVersion structure_version = 1; + + SubtopicId id = 2; + string title = 3; + SubtitledHtml content = 4; + RecordedVoiceovers recorded_voiceovers = 5; + WrittenTranslations written_translations = 6; + Thumbnail thumbnail = 7; + ReferencedImageList referenced_image_list = 8; +} + +// This structure is shared among multiple parent structures, so it has no direct migration pathway. Changes should be carefully done, or the structure should be duplicated according to whichever structure requires alterations. +message SubtopicId { + string topic_id = 1; + int32 index = 2; +} diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto new file mode 100644 index 0000000..2484d7d --- /dev/null +++ b/proto/v1/structure/state.proto @@ -0,0 +1,455 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/languages.proto"; +import "proto/v1/structure/objects.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message State { + StateStructureVersion structure_version = 1; + + SubtitledHtml content = 2; + InteractionInstance interaction = 3; + RecordedVoiceovers recorded_voiceovers = 4; + WrittenTranslations written_translations = 5; +} + +// Structure corresponds to StateStructureVersion. +message InteractionInstance { + oneof interaction_type { + ContinueInstance continue = 1; + FractionInputInstance fraction_input = 2; + ItemSelectionInputInstance item_selection_input = 3; + MultipleChoiceInputInstance multiple_choice_input = 4; + NumericInputInstance numeric_input = 5; + TextInputInstance text_input = 6; + DragAndDropSortInputInstance drag_and_drop_sort_input = 7; + ImageClickInputInstance image_click_input = 8; + RatioExpressionInputInstance ratio_expression_input = 9; + EndExplorationInstance end_exploration = 10; + } +} + +// Answer type: none (N/A since no answers are submitted for this interaction). +// Structure corresponds to StateStructureVersion. +message ContinueInstance { + CustomizationArgs customization_args = 1; + Outcome default_outcome = 2; + + // Continue interactions cannot have custom answer groups, and do not support + // solutions. Users cannot receive hints since only one answer is possible + // (clicking the button). + + message CustomizationArgs { + // Note that while the continue interaction has a default button text + // defined, it's not used in the app since the default string needs to come + // through the app's strings so that it can be translated. + SubtitledHtml button_text = 1; + } +} + +// Answer type: Fraction. +// Structure corresponds to StateStructureVersion. +message FractionInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + Solution solution = 5; + + message CustomizationArgs { + bool requires_simplest_form = 1; + bool allow_improper_fractions = 2; + bool allow_nonzero_integer_part = 3; + SubtitledHtml custom_placeholder = 4; + } + message Solution { + BaseSolution base_solution = 1; + Fraction correct_answer = 2; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + IsExactlyEqualToSpec is_exactly_equal_to = 1; + IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToAndInSimplestFormSpec is_equivalent_to_and_in_simplest_form = 3; + IsLessThanSpec is_less_than = 4; + IsGreaterThanSpec is_greater_than = 5; + HasNumeratorEqualToSpec has_numerator_equal_to = 6; + HasDenominatorEqualToSpec has_denominator_equal_to = 7; + HasIntegerPartEqualToSpec has_integer_part_equal_to = 8; + HasNoFractionalPartSpec has_no_fractional_part = 9; + HasFractionalPartExactlyEqualToSpec has_fractional_part_exactly_equal_to = 10; + } + message IsExactlyEqualToSpec { + Fraction input = 1; + } + message IsEquivalentToSpec { + Fraction input = 1; + } + message IsEquivalentToAndInSimplestFormSpec { + Fraction input = 1; + } + message IsLessThanSpec { + Fraction input = 1; + } + message IsGreaterThanSpec { + Fraction input = 1; + } + message HasNumeratorEqualToSpec { + int32 input = 1; + } + message HasDenominatorEqualToSpec { + uint32 input = 1; + } + message HasIntegerPartEqualToSpec { + int32 input = 1; + } + message HasNoFractionalPartSpec { + // No inputs for this rule spec. + } + message HasFractionalPartExactlyEqualToSpec { + Fraction input = 1; + } + } +} + +// Answer type: SetOfTranslatableHtmlContentIds. +// Structure corresponds to StateStructureVersion. +message ItemSelectionInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + + // Item selection does not support solutions. + + message CustomizationArgs { + int32 min_allowable_selection_count = 1; + int32 max_allowable_selection_count = 2; + repeated SubtitledHtml choices = 3; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + EqualsSpec equals = 1; + ContainsAtLeastOneOfSpec contains_at_least_one_of = 2; + DoesNotContainAtLeastOneOfSpec does_not_contain_at_least_one_of = 3; + IsProperSubsetOfSpec is_proper_subset_of = 4; + } + message EqualsSpec { + SetOfTranslatableHtmlContentIds input = 1; + } + message ContainsAtLeastOneOfSpec { + SetOfTranslatableHtmlContentIds input = 1; + } + message DoesNotContainAtLeastOneOfSpec { + SetOfTranslatableHtmlContentIds input = 1; + } + message IsProperSubsetOfSpec { + SetOfTranslatableHtmlContentIds input = 1; + } + } +} + +// Answer type: non-negative int (uint32). +// Structure corresponds to StateStructureVersion. +message MultipleChoiceInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + + // Multiple choice does not support solutions. + + message CustomizationArgs { + repeated SubtitledHtml choices = 1; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + EqualsSpec equals = 1; + } + message EqualsSpec { + uint32 input = 1; + } + } +} + +// Answer type: real (double). +// Structure corresponds to StateStructureVersion. +message NumericInputInstance { + repeated AnswerGroup answer_groups = 1; + Solution solution = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + + // Numeric input does not have any customization arguments. + + message Solution { + BaseSolution base_solution = 1; + double correct_answer = 2; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + EqualsSpec equals = 1; + IsLessThanSpec is_less_than = 2; + IsGreaterThanSpec is_greater_than = 3; + IsLessThanOrEqualToSpec is_less_than_or_equal_to = 4; + IsGreaterThanOrEqualToSpec is_greater_than_or_equal_to = 5; + IsInclusivelyBetweenSpec is_inclusively_between = 6; + IsWithinToleranceSpec is_within_tolerance = 7; + } + message EqualsSpec { + double input = 1; + } + message IsLessThanSpec { + double input = 1; + } + message IsGreaterThanSpec { + double input = 1; + } + message IsLessThanOrEqualToSpec { + double input = 1; + } + message IsGreaterThanOrEqualToSpec { + double input = 1; + } + message IsInclusivelyBetweenSpec { + double inputLowerInclusive = 1; + double inputUpperInclusive = 2; + } + message IsWithinToleranceSpec { + double inputTolerance = 1; + double inputComparedValue = 2; + } + } +} + +// Answer type: normalized string (string). +// Structure corresponds to StateStructureVersion. +message TextInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + Solution solution = 5; + + message CustomizationArgs { + SubtitledHtml placeholder = 1; + int32 rows = 2; + } + message Solution { + BaseSolution base_solution = 1; + string correct_answer = 2; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + EqualsSpec equals = 1; + StartsWithSpec starts_with = 2; + ContainsSpec contains = 3; + FuzzyEqualsSpec fuzzy_equals = 4; + } + message EqualsSpec { + TranslatableSetOfNormalizedString input = 1; + } + message StartsWithSpec { + TranslatableSetOfNormalizedString input = 1; + } + message ContainsSpec { + TranslatableSetOfNormalizedString input = 1; + } + message FuzzyEqualsSpec { + TranslatableSetOfNormalizedString input = 1; + } + } +} + +// Answer type: ListOfSetsOfTranslatableHtmlContentIds. +// Structure corresponds to StateStructureVersion. +message DragAndDropSortInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + Solution solution = 5; + + message CustomizationArgs { + repeated SubtitledHtml choices = 1; + bool allowMultipleItemsInSamePosition = 2; + } + message Solution { + BaseSolution base_solution = 1; + ListOfSetsOfTranslatableHtmlContentIds correct_answer = 2; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + IsEqualToOrderingSpec is_equal_to_ordering = 1; + IsEqualToOrderingWithOneItemAtIncorrectPositionSpec is_equal_to_ordering_with_one_item_at_incorrect_position = 2; + HasElementXAtPositionYSpec has_element_x_at_position_y = 3; + HasElementXBeforeElementYSpec has_element_x_before_element_y = 4; + } + message IsEqualToOrderingSpec { + ListOfSetsOfTranslatableHtmlContentIds input = 1; + } + message IsEqualToOrderingWithOneItemAtIncorrectPositionSpec { + ListOfSetsOfTranslatableHtmlContentIds input = 1; + } + message HasElementXAtPositionYSpec { + TranslatableHtmlContentId element = 1; + uint32 position = 2; + } + message HasElementXBeforeElementYSpec { + TranslatableHtmlContentId considered_element = 1; + TranslatableHtmlContentId later_element = 2; + } + } +} + +// Answer type: ClickOnImage. +// Structure corresponds to StateStructureVersion. +message ImageClickInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + + // Image click input doesn't yet support solutions. + + message CustomizationArgs { + ImageWithRegions image_and_regions = 1; + reserved 2; // highlight_regions_on_hover which is not supported on Android. + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + IsInRegionSpec is_in_region = 1; + } + message IsInRegionSpec { + string input_region = 1; + } + } +} + +// Answer type: RatioExpression. +// Structure corresponds to StateStructureVersion. +message RatioExpressionInputInstance { + CustomizationArgs customization_args = 1; + repeated AnswerGroup answer_groups = 2; + Outcome default_outcome = 3; + repeated Hint hints = 4; + Solution solution = 5; + + message CustomizationArgs { + SubtitledHtml placeholder = 1; + int32 number_of_terms = 2; + } + message Solution { + BaseSolution base_solution = 1; + RatioExpression correct_answer = 2; + } + message AnswerGroup { + BaseAnswerGroup base_answer_group = 1; + repeated RuleSpec rule_specs = 2; + } + message RuleSpec { + oneof rule_type { + EqualsSpec equals = 1; + IsEquivalentSpec is_equivalent = 2; + HasNumberOfTermsEqualToSpec has_number_of_terms_equal_to = 3; + } + message EqualsSpec { + RatioExpression input = 1; + } + message IsEquivalentSpec { + RatioExpression input = 1; + } + message HasNumberOfTermsEqualToSpec { + uint32 input_term_count = 1; + } + } +} + +// Answer type: none (N/A since no answers are submitted for this interaction). +// Structure corresponds to StateStructureVersion. +message EndExplorationInstance { + // No answers can be submitted to the end exploration, so there are neither + // answer groups nor solutions. The interaction does have customization + // arguments, but they aren't supported in the Android app. No default outcome + // is possible since the user takes no interactions. No hints can be shown to + // the user. +} + +// Common fields for all answer groups. +// Structure corresponds to StateStructureVersion. +message BaseAnswerGroup { + Outcome outcome = 1; + Misconception tagged_skill_misconception = 2; +} + +// Structure corresponds to StateStructureVersion. +message Outcome { + string destination_state = 1; + SubtitledHtml feedback = 2; + bool labelled_as_correct = 3; + reserved 4; // param_changes + reserved 5; // refresher_exploration_id + reserved 6; // missing_prerequisite_skill_id +} + +// Structure corresponds to StateStructureVersion. +message Hint { + SubtitledHtml hint_content = 1; +} + +// Common fields for all solutions. +// Structure corresponds to StateStructureVersion. +message BaseSolution { + SubtitledHtml explanation = 1; +} + +// Convenience collection object for all potential types of solutions. +// Structure corresponds to StateStructureVersion. +message Solution { + oneof interaction_type { + FractionInputInstance.Solution fraction_instance_solution = 1; + NumericInputInstance.Solution numeric_input_instance_solution = 2; + TextInputInstance.Solution text_input_instance_solution = 3; + DragAndDropSortInputInstance.Solution drag_and_drop_sort_input_instance_solution = 4; + RatioExpressionInputInstance.Solution ratio_expression_input_instance_solution = 5; + } +} + +// Structure corresponds to StateStructureVersion. +message Misconception { + string skill_id = 1; + string misconception_id = 2; +} diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto new file mode 100644 index 0000000..7c7e0eb --- /dev/null +++ b/proto/v1/structure/topic_summary.proto @@ -0,0 +1,58 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "proto/v1/structure/image.proto"; +import "proto/v1/structure/versions.proto"; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message TopicSummary { + TopicSummaryStructureVersion structure_version = 1; + + string id = 2; + string name = 3; + string description = 4; + oneof download_type { + int32 download_size_bytes = 5; + int32 update_size_bytes = 6; + } + repeated StorySummary story_summaries = 7; + repeated int32 subtopic_indexes = 8; + Thumbnail thumbnail = 9; // TODO + bool is_published = 10; + int32 model_version = 11; +} + +// Structure version corresponds to TopicSummaryStructureVersion. +message StorySummary { + string id = 1; + string title = 2; + string description = 3; + Thumbnail thumbnail = 4; // TODO + repeated ChapterSummary chapters = 5; + int32 model_version = 6; +} + +// Structure version corresponds to TopicSummaryStructureVersion. +message ChapterSummary { + Thumbnail thumbnail = 1; // TODO + string title = 2; + string exploration_id = 3; + int32 model_version = 4; +} + +// Structure version corresponds to TopicSummaryStructureVersion. +message SubtopicSummary { + int32 index = 1; + repeated SkillSummary skill_summaries = 2; + int32 model_version = 3; +} + +// Structure version corresponds to TopicSummaryStructureVersion. +message SkillSummary { + string id = 1; + string name = 2; + int32 model_version = 4; +} diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto new file mode 100644 index 0000000..e440f2b --- /dev/null +++ b/proto/v1/structure/versions.proto @@ -0,0 +1,39 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +option java_package = "org.oppia.v1.structure"; +option java_multiple_files = true; + +message TopicSummaryStructureVersion { + int32 version = 1; +} + +message RevisionCardStructureVersion { + int32 version = 1; +} + +message ConceptCardStructureVersion { + int32 version = 1; +} + +message ExplorationStructureVersion { + int32 version = 1; +} + +message QuestionStructureVersion { + int32 version = 1; +} + +// This version implies interaction compatibility since interactions are tightly defined in the structures. +message StateStructureVersion { + int32 version = 1; +} + +message LanguageStructuresVersion { + int32 version = 1; +} + +message ImageStructureVersion { + int32 version = 1; +} From a69a240300a1e307dcf7ae888465308ae70ab7c3 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 6 Aug 2021 00:23:40 -0700 Subject: [PATCH 02/51] Rename 'model' version to be content, instead. --- proto/v1/api/android.proto | 2 +- proto/v1/structure/exploration.proto | 2 +- proto/v1/structure/question.proto | 2 +- proto/v1/structure/topic_summary.proto | 10 +++++----- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 8b0256a..021e770 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -78,7 +78,7 @@ message ClientCompatibilityContext { message ClientDownloadStateContext { message DownloadState { - int32 model_version = 1; + int32 content_version = 1; oneof structure_type { string topic_id = 2; // in summary org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; // in summary diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 1d47045..15de7f3 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -16,6 +16,6 @@ message Exploration { string title = 3; string init_state_name = 4; map states = 5; - int32 model_version = 6; + int32 content_version = 6; ReferencedImageList referenced_image_list = 7; } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index ed26281..6ef6ff7 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -15,6 +15,6 @@ message Question { string id = 2; State question_state = 3; repeated string linked_skill_ids = 4; - int32 model_version = 5; + int32 content_version = 5; ReferencedImageList referenced_image_list = 6; } diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index 7c7e0eb..a40a6e3 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -22,7 +22,7 @@ message TopicSummary { repeated int32 subtopic_indexes = 8; Thumbnail thumbnail = 9; // TODO bool is_published = 10; - int32 model_version = 11; + int32 content_version = 11; } // Structure version corresponds to TopicSummaryStructureVersion. @@ -32,7 +32,7 @@ message StorySummary { string description = 3; Thumbnail thumbnail = 4; // TODO repeated ChapterSummary chapters = 5; - int32 model_version = 6; + int32 content_version = 6; } // Structure version corresponds to TopicSummaryStructureVersion. @@ -40,19 +40,19 @@ message ChapterSummary { Thumbnail thumbnail = 1; // TODO string title = 2; string exploration_id = 3; - int32 model_version = 4; + int32 content_version = 4; } // Structure version corresponds to TopicSummaryStructureVersion. message SubtopicSummary { int32 index = 1; repeated SkillSummary skill_summaries = 2; - int32 model_version = 3; + int32 content_version = 3; } // Structure version corresponds to TopicSummaryStructureVersion. message SkillSummary { string id = 1; string name = 2; - int32 model_version = 4; + int32 content_version = 4; } From b41cf7d71c5644683c15d78bf1f89e5f7b40f2fa Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:16:55 +0530 Subject: [PATCH 03/51] structure version -> proto version --- proto/v1/structure/concept_card.proto | 2 +- proto/v1/structure/topic_summary.proto | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index c0a7af2..33f2f77 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -20,7 +20,7 @@ message ConceptCard { WrittenTranslations written_translations = 7; ReferencedImageList referenced_image_list = 8; - // Structure version corresponds to ConceptCardStructureVersion. + // Proto version corresponds to ConceptCardStructureVersion. message WorkedExample { SubtitledHtml question = 1; SubtitledHtml explanation = 2; diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index a40a6e3..11d7bfe 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -25,7 +25,7 @@ message TopicSummary { int32 content_version = 11; } -// Structure version corresponds to TopicSummaryStructureVersion. +// Proto version corresponds to TopicSummaryStructureVersion. message StorySummary { string id = 1; string title = 2; @@ -35,7 +35,7 @@ message StorySummary { int32 content_version = 6; } -// Structure version corresponds to TopicSummaryStructureVersion. +// Proto version corresponds to TopicSummaryStructureVersion. message ChapterSummary { Thumbnail thumbnail = 1; // TODO string title = 2; @@ -43,14 +43,14 @@ message ChapterSummary { int32 content_version = 4; } -// Structure version corresponds to TopicSummaryStructureVersion. +// Proto version corresponds to TopicSummaryStructureVersion. message SubtopicSummary { int32 index = 1; repeated SkillSummary skill_summaries = 2; int32 content_version = 3; } -// Structure version corresponds to TopicSummaryStructureVersion. +// Proto version corresponds to TopicSummaryStructureVersion. message SkillSummary { string id = 1; string name = 2; From be028d260925471398120fff2f25e230c27e0fe1 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:20:21 +0530 Subject: [PATCH 04/51] StructureDownloadResult to DownloadResult --- proto/v1/api/android.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 021e770..e4dbec9 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -38,10 +38,10 @@ message TopicContentRequest { message TopicContentResponse { TopicContentRequestResponseStructureVersion structure_version = 1; - repeated StructureDownloadResult download_results = 2; + repeated DownloadResult download_results = 2; // Structure corresponds to TopicContentRequestResponseStructureVersion. - message StructureDownloadResult { + message DownloadResult { DownloadRequestStructureIdentifier identifier = 1; oneof structure_type { From 0ab3fc3532350a243dd7075a7d69ab40321e686e Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:22:33 +0530 Subject: [PATCH 05/51] ClientCompatibilityContext index fixed --- proto/v1/api/android.proto | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index e4dbec9..cdbfed8 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -67,13 +67,13 @@ message ClientContext { message ClientCompatibilityContext { org.oppia.proto.v1.structure.TopicSummaryStructureVersion topic_summary_structure_version = 1; - org.oppia.proto.v1.structure.RevisionCardStructureVersion revision_card_structure_version = 3; - org.oppia.proto.v1.structure.ConceptCardStructureVersion concept_card_structure_version = 4; - org.oppia.proto.v1.structure.ExplorationStructureVersion exploration_structure_version = 5; - org.oppia.proto.v1.structure.QuestionStructureVersion question_structure_version = 6; - org.oppia.proto.v1.structure.StateStructureVersion state_structure_version = 7; - org.oppia.proto.v1.structure.LanguageStructuresVersion language_structures_version = 8; - org.oppia.proto.v1.structure.ImageStructureVersion thumbnail_structure_version = 9; + org.oppia.proto.v1.structure.RevisionCardStructureVersion revision_card_structure_version = 2; + org.oppia.proto.v1.structure.ConceptCardStructureVersion concept_card_structure_version = 3; + org.oppia.proto.v1.structure.ExplorationStructureVersion exploration_structure_version = 4; + org.oppia.proto.v1.structure.QuestionStructureVersion question_structure_version = 5; + org.oppia.proto.v1.structure.StateStructureVersion state_structure_version = 6; + org.oppia.proto.v1.structure.LanguageStructuresVersion language_structures_version = 7; + org.oppia.proto.v1.structure.ImageStructureVersion thumbnail_structure_version = 8; } message ClientDownloadStateContext { From abbdf136119835b0a5b4ca925235dbca5b2c85d2 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:27:12 +0530 Subject: [PATCH 06/51] removed all placeholder comments --- proto/v1/api/android.proto | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index cdbfed8..8aafc93 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -80,11 +80,11 @@ message ClientDownloadStateContext { message DownloadState { int32 content_version = 1; oneof structure_type { - string topic_id = 2; // in summary - org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; // in summary + string topic_id = 2; + org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; string concept_card_id = 4; - string story_id = 5; // in summary - string exploration_id = 6; // in summary + string story_id = 5; + string exploration_id = 6; string question_id = 7; string skill_id = 8; } From c1e97fde94a2b8e8361b560ea1a9f8251c0ab651 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:32:11 +0530 Subject: [PATCH 07/51] renaming fields of WrittenTranslation --- proto/v1/structure/languages.proto | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 1b4da0d..a04d776 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -67,20 +67,20 @@ message WrittenTranslation { // Structure corresponds to LanguageStructuresVersion. message WrittenTranslatableHtml { - string translation_html = 1; + string translation = 1; } // Structure corresponds to LanguageStructuresVersion. message WrittenTranslatableUnicode { - string translation_unicode = 1; + string translation = 1; } // Structure corresponds to LanguageStructuresVersion. message WrittenTranslatableSetOfNormalizedString { - repeated string translations = 1; + repeated string translation = 1; } // Structure corresponds to LanguageStructuresVersion. message WrittenTranslatableSetOfUnicodeString { - repeated string unicode_translations = 1; + repeated string translation = 1; } From 0e921d10f0f3bace12fd2ef5486c9242c9db02f1 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 13:35:03 +0530 Subject: [PATCH 08/51] adding Brazilian and Portuguese in LanguageCode --- proto/v1/structure/languages.proto | 2 ++ 1 file changed, 2 insertions(+) diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index a04d776..d3759ed 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -14,6 +14,8 @@ enum LanguageCode { ARABIC = 2; HINDI = 3; HINGLISH = 4; + BRAZILIAN = 5; + PORTUGUESE = 6; } message SubtitledHtml { From f6b3210577b2f10679fd1ef3d595465b27cd643a Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 17:15:55 +0530 Subject: [PATCH 09/51] remove reserved fields --- proto/v1/structure/languages.proto | 3 +-- proto/v1/structure/state.proto | 4 ---- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index d3759ed..5d11fd5 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -41,8 +41,7 @@ message VoiceoverContentMapping { message Voiceover { string filename = 1; int32 file_size_bytes = 2; - reserved 3; // needs_update - float duration_secs = 4; + float duration_secs = 3; } message WrittenTranslations { diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 2484d7d..1b77c7b 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -343,7 +343,6 @@ message ImageClickInputInstance { message CustomizationArgs { ImageWithRegions image_and_regions = 1; - reserved 2; // highlight_regions_on_hover which is not supported on Android. } message AnswerGroup { BaseAnswerGroup base_answer_group = 1; @@ -420,9 +419,6 @@ message Outcome { string destination_state = 1; SubtitledHtml feedback = 2; bool labelled_as_correct = 3; - reserved 4; // param_changes - reserved 5; // refresher_exploration_id - reserved 6; // missing_prerequisite_skill_id } // Structure corresponds to StateStructureVersion. From 47dfb60f7736af52854700ef4c4b7c09b8333a5c Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 10 Aug 2021 17:47:49 +0530 Subject: [PATCH 10/51] added docs for bazel files --- BUILD | 1 - WORKSPACE | 2 +- proto/v1/api/BUILD | 5 ++++- proto/v1/structure/BUILD | 5 ++++- 4 files changed, 9 insertions(+), 4 deletions(-) diff --git a/BUILD b/BUILD index 8dbc40f..defc796 100644 --- a/BUILD +++ b/BUILD @@ -25,7 +25,6 @@ java_library( ], ) - java_library( name = "android_java_lite_protos", visibility = ["//visibility:public"], diff --git a/WORKSPACE b/WORKSPACE index 8b3fff8..0b4760f 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -1,5 +1,5 @@ """ -TODO: fill in +This file lists and imports all external dependencies needed to build Oppia Proto API. """ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD index 5c66232..02a7a11 100644 --- a/proto/v1/api/BUILD +++ b/proto/v1/api/BUILD @@ -1,5 +1,8 @@ """ -TODO: fill in +This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. +The proto_library() rule creates a proto file library for the android API proto file to be used in multiple languages. +The java_lite_proto_library() rule takes in a proto_library target and generates Java code. +The java_proto_library() rule takes in a proto_library target and generate Java code. """ load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") diff --git a/proto/v1/structure/BUILD b/proto/v1/structure/BUILD index fb61c62..be4d187 100644 --- a/proto/v1/structure/BUILD +++ b/proto/v1/structure/BUILD @@ -1,5 +1,8 @@ """ -TODO: fill in +This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. +The proto_library() rule creates a proto file library for the core proto files to be used in multiple languages. +The java_lite_proto_library() rule takes in a proto_library target and generates Java code. +The java_proto_library() rule takes in a proto_library target and generate Java code. """ load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") From 8dc3eb1e6a67b7cc8f9021a298bf825d38c95516 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Wed, 11 Aug 2021 08:41:37 +0530 Subject: [PATCH 11/51] brazilian portuguese language fix --- proto/v1/structure/languages.proto | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 5d11fd5..d39696e 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -14,8 +14,7 @@ enum LanguageCode { ARABIC = 2; HINDI = 3; HINGLISH = 4; - BRAZILIAN = 5; - PORTUGUESE = 6; + BRAZILIAN_PORTUGUESE = 5; } message SubtitledHtml { From a5edbf5a45e4557b5cae4e4cf1d459a2bfd50115 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Wed, 11 Aug 2021 09:29:04 +0530 Subject: [PATCH 12/51] updated readme --- README.md | 39 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d3a516f..6de2b54 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,37 @@ -# oppia-android-api -Published Android-specific API for the Oppia backend. +# oppia-proto-api +Published required API for the Oppia backend. + +## Versioning +Versioning starts getting a bit complicated when considering the backend VersionedModels, the model structures themselves, schema structures, proto structures, the API, snapshots of the API, and other things. To try and keep things simple, this design intends to define a _separate_ set of versions that are specific to this API. How these map to Oppia backend's many versions is an implementation detail not actually relevant to this design. + +### API version +The API itself is versioned and has separate releases. To keep things simple, it has a major & minor version (e.g. 1.0). The major version is represented directly in the directory structure (e.g. 'v1') since the repository could, in the future, house multiple major versions (which is necessary for the backend to maintain long-term backward compatibility with older API versions). The major version is only incremented if a breaking change must be introduced into the API (generally this will only come when we want to make substantial changes to the API/redesign it). + +The API's minor version essentially counts the number of releases that major version has been changed. This means we increment the minor version anytime we make a compatible change to the API, and then release it. The main benefit of having distinct releases is it allows the backend & frontends to opt into taking on a particular version of the API. Due to the backward/forward interoperability nature of protobuf, it's unlikely there will ever be an incompatibility so long as structure versions are respected (see below), and even in those cases there should be potential for graceful failures. Note that the minor version is only ever represented in the release numbers and never in code form since it only serves the purpose of cataloging. + +### Content versions +Content versions are meant to be the version of the entity itself corresponding to a particular structure (such as a topic, skill, or exploration). These are used to track whether there are content updates for a particular structure. These are expected to map exactly to the versions stored in the corresponding structure's VersionedModel in the backend, but how this versioning behaves is up to the backend so long as it's monotonically increasing and positive. + +### Structure versions +Structure versions correspond to groups of proto structures themselves. These are unique versions to the proto structures and are **not** shared with schema structure versions in the backend. Generally, these only need to be incremented when a proto structure is updated in such a way that the default data will break existing logical assumptions (thus requiring a data migration). Proto structures should never be updated in an incompatible way (without incrementing the major version--see the API version section above), but sometimes data migrations are necessary and these versions help track when those need to occur. Unlike schema versions in the backend, these are likely to not increment as often since most proto changes can be safely ignored by older clients. + +Note that one aspect of this is a bit complicated: some of the substructures are shared across high-level structures (such as SubtitledHtml, or other language-based substructures). To ensure these are properly tracked, some substructures are grouped into their own combined version to track changes. The following are the list of structure types whose versions are tracked: +- TopicSummaryStructureVersion +- RevisionCardStructureVersion +- ConceptCardStructureVersion +- ExplorationStructureVersion +- QuestionStructureVersion +- StateStructureVersion +- LanguageStructuresVersion +- ImageStructureVersion + +#### A note on interaction versioning +I did want to briefly note that it was discovered during the creation of this PR & structure versions that separate versioning for interactions is not actually needed since, per the strong typing of State's substructures, the structures of individual interactions & how they relate to the exploration/question experience is implied as part of State's structure version. This does not mean the backend won't need additional version tracking for interactions in order to compute compatibility with specific proto State structure versions, but it does serendipitously simplify version tracking at the sub-State level a bit. + +## Support +If you have any feature requests or bug reports, please log them on our [issue tracker](https://github.com/oppia/oppia-proto-api/issues/new?title=Describe%20your%20feature%20request%20or%20bug%20report%20succinctly&body=If%20you%27d%20like%20to%20propose%20a%20feature,%20describe%20what%20you%27d%20like%20to%20see.%0A%0AIf%20you%27re%20reporting%20a%20bug,%20please%20be%20sure%20to%20include%20the%20expected%20behaviour,%20the%20observed%20behaviour,%20and%20steps%20to%20reproduce%20the%20problem.%20Console%20copy-pastes%20and%20any%20background%20on%20the%20environment%20would%20also%20be%20helpful.%0A%0AThanks!). + +Please report security issues directly to admin@oppia.org. + +## Licence +The Oppia-Proto-API code is released under the [Apache v2 license](https://github.com/oppia/oppia-proto-api/blob/master/LICENSE). From 13fad56ecca74e01f2a66574130e8a912193d2bf Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 13 Aug 2021 11:49:44 +0530 Subject: [PATCH 13/51] added doc for proto --- proto/v1/api/android.proto | 4 ++- proto/v1/structure/concept_card.proto | 17 +++++++++ proto/v1/structure/exploration.proto | 11 ++++++ proto/v1/structure/image.proto | 4 +++ proto/v1/structure/languages.proto | 22 +++++++++++- proto/v1/structure/objects.proto | 45 +++++++++++++++++++++++ proto/v1/structure/question.proto | 8 +++++ proto/v1/structure/revision_card.proto | 12 +++++++ proto/v1/structure/state.proto | 39 ++++++++++++++++++++ proto/v1/structure/topic_summary.proto | 49 ++++++++++++++++++++++++++ 10 files changed, 209 insertions(+), 2 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 8aafc93..a813d53 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -45,7 +45,9 @@ message TopicContentResponse { DownloadRequestStructureIdentifier identifier = 1; oneof structure_type { - bool skipped_suggest_retry = 2; + // Indicates that the request corresponding to this particular identifier was skipped and suggested to retry by the Oppia backend. + // Note that the presence of this value in the oneof is sufficient to indicate its state, and its actual value does not matter. + bool skipped = 2; org.oppia.proto.v1.structure.RevisionCard revision_card = 3; org.oppia.proto.v1.structure.ConceptCard concept_card = 4; org.oppia.proto.v1.structure.Exploration exploration = 5; diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index 33f2f77..3318af6 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,20 +9,37 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure of the single concept card that can be displayed for a specific skill. message ConceptCard { ConceptCardStructureVersion structure_version = 1; + // The ID corresponding to the skill this concept is representing. string skill_id = 2; + + // The skill's description that can help provide context on what content is being reviewed. string description = 3; + + // The core explanation of the skill being reviewed. SubtitledHtml explanation = 4; + + // A list of worked examples to present to the learner. repeated WorkedExample worked_examples = 5; + + // Recorded audio to play for each SubtitledHtml in this concept card. RecordedVoiceovers recorded_voiceovers = 6; + + // Translations for each SubtitledHtml in this concept card. WrittenTranslations written_translations = 7; + ReferencedImageList referenced_image_list = 8; // Proto version corresponds to ConceptCardStructureVersion. message WorkedExample { + + // Question of the worked example in the SubtitledHtml format. SubtitledHtml question = 1; + + // Explanation of the worked example in the SubtitledHtml format. SubtitledHtml explanation = 2; } } diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 15de7f3..8eb8958 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,13 +9,24 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure for a single exploration. message Exploration { ExplorationStructureVersion structure_version = 1; + // The ID of the exploration. string id = 2; + + // The title of the exploration. string title = 3; + + // The name of the state which initialize the exploration. string init_state_name = 4; + + // Mapping from a state name to a state object map states = 5; + + // The version of the exploration. int32 content_version = 6; + ReferencedImageList referenced_image_list = 7; } diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 8327b7e..0ad6247 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,10 +7,14 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure for the single thumbnail. message Thumbnail { ImageStructureVersion structure_version = 1; + // Name of the thumbnail file. string filename = 2; + + // Background color of the thumbnail to use it explicitly in case of required for blurring the image. int32 background_color_rgb = 3; } diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index d39696e..2205244 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -17,16 +17,23 @@ enum LanguageCode { BRAZILIAN_PORTUGUESE = 5; } + +// Strucutre of the single subtitled html. message SubtitledHtml { LanguageStructuresVersion structure_version = 1; + // Id of the content whomsoever corresponds to SubtitledHtml. string content_id = 2; + + // Html format data of the content whomsoever corresponds to SubtitledHtml. string html = 3; } +// Strucutre of the single recorded voiceover. message RecordedVoiceovers { LanguageStructuresVersion structure_version = 1; + // All the voiceover corresponds to the LanguageStructuresVersion. repeated VoiceoverContentMapping voiceover_language_mapping = 2; } @@ -38,14 +45,19 @@ message VoiceoverContentMapping { // Structure corresponds to LanguageStructuresVersion. message Voiceover { + + // File name of the voiceover. string filename = 1; + + // Size of voiceover file. int32 file_size_bytes = 2; + + // Duration of voiceover. float duration_secs = 3; } message WrittenTranslations { LanguageStructuresVersion structure_version = 1; - repeated WrittenTranslationContentMapping translation_language_mapping = 2; } @@ -58,9 +70,17 @@ message WrittenTranslationContentMapping { // Structure corresponds to LanguageStructuresVersion. message WrittenTranslation { oneof data_format { + + // Html format data of the translation. WrittenTranslatableHtml translatable_html = 1; + + // Unicode format data of the translation. WrittenTranslatableUnicode translatable_unicode = 2; + + // Set of normalized string of the translation. WrittenTranslatableSetOfNormalizedString translatable_set_of_normalized_string = 3; + + // Set of unicode string of the translation. WrittenTranslatableSetOfUnicodeString translatable_set_of_unicode_string = 4; } } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index efdf64c..c95c817 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -5,54 +5,99 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure of the single Fraction. message Fraction { + + // Boolean to check if fraction is negative or not. bool is_negative = 1; + + // Whole number of the fraction. uint32 whole_number = 2; + + // Numerator of the fraction. uint32 numerator = 3; + + // Denominator of the fraction. int32 denominator = 4; } +// Corresponds to a single string value as designated by a content ID. The value for this +// translatable content will be present in the written translations structure of the containing +// State. message TranslatableHtmlContentId { string content_id = 1; } +// Corresponds to a set of TranslatableHtmlContentIds. message SetOfTranslatableHtmlContentIds { repeated TranslatableHtmlContentId content_ids = 1; } +// Corresponds to a list of SetOfTranslatableHtmlContentIds. message ListOfSetsOfTranslatableHtmlContentIds { repeated SetOfTranslatableHtmlContentIds content_id_lists = 1; } +// 2-Dimensional Point for interaction type image region selection. message Point2d { + + // x axis. double x = 1; + + // y axis. double y = 2; } + +// Click action on image for for interaction type image region selection. message ClickOnImage { + + // X,Y coordinates where user clicked on image. Point2d click_position = 1; + + // All the selected regions on the image. repeated string clicked_regions = 2; } +// Structure containing a ratio object for eg - [1,2,3] for 1:2:3. message RatioExpression { + // List of components in a ratio. It's expected that list should have more than + // 1 element. repeated uint32 components = 1; } +// Corresponds to a set of normalized strings which are described in this structure, but which have +// replacement translations findable in the written translations structure of the containing State. message TranslatableSetOfNormalizedString { string content_id = 1; + + // All the normalized strings. repeated string normalized_strings = 2; } +// An image overlaid with labeled regions. message ImageWithRegions { + + // A string that represents a filepath which will be prefixed with '[exploration_id]/assets. string image_file_path = 1; + + // All the labeled regions in this ImageWithRegions. repeated LabeledRegion labeled_regions = 2; + // A region of an image, including its shape and coordinates. message LabeledRegion { + + // The name for the region. string label = 3; + + // Represents the different Region Types. oneof region_type { + + // A rectangle normalized so that the coordinates are within the range [0,1]. NormalizedRectangle2d normalized_rectangle_2d = 1; } message NormalizedRectangle2d { + // Origin is top-left, increasing x is to the right, increasing y is down. Point2d upper_left = 1; Point2d lower_right = 2; } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 6ef6ff7..7460c91 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,12 +9,20 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure of the single question. message Question { QuestionStructureVersion structure_version = 1; + + // Id of the question. string id = 2; + + // Question state is the name of the state to which this question belongs. State question_state = 3; + + // All the skill ids which belongs to this question. repeated string linked_skill_ids = 4; + int32 content_version = 5; ReferencedImageList referenced_image_list = 6; } diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index a5dccde..3d4de81 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,15 +9,27 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Corresponds to a revision card that can be displayed for a specific subtopic. message RevisionCard { RevisionCardStructureVersion structure_version = 1; SubtopicId id = 2; + + // The title corresponding to the subtopic. string title = 3; + + // The core explanation of the subtopic being revised. SubtitledHtml content = 4; + + // The recorded voiceovers to play for the corresponding revision card. RecordedVoiceovers recorded_voiceovers = 5; + + // The written translations of the revision card. WrittenTranslations written_translations = 6; + + // The thumbnail of the revision card. Thumbnail thumbnail = 7; + ReferencedImageList referenced_image_list = 8; } diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 1b77c7b..45eada3 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,27 +9,57 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure for a single state message State { StateStructureVersion structure_version = 1; + // Content of the state. SubtitledHtml content = 2; + + // Interactions of the state. InteractionInstance interaction = 3; + + // Recorded Voiceovers of the state. RecordedVoiceovers recorded_voiceovers = 4; + + // Written Translations of the state. WrittenTranslations written_translations = 5; } // Structure corresponds to StateStructureVersion. message InteractionInstance { + + // Different type of interactions. oneof interaction_type { + + // Continue interaction. ContinueInstance continue = 1; + + // Fraction input interaction. FractionInputInstance fraction_input = 2; + + // Single item selection interaction. ItemSelectionInputInstance item_selection_input = 3; + + // Multiple choice selection interaction. MultipleChoiceInputInstance multiple_choice_input = 4; + + // Numeric input interaction. NumericInputInstance numeric_input = 5; + + // Text input interaction. TextInputInstance text_input = 6; + + // Drag and drop type interaction. DragAndDropSortInputInstance drag_and_drop_sort_input = 7; + + // Image region click interaction. ImageClickInputInstance image_click_input = 8; + + // Ratio input interaction. RatioExpressionInputInstance ratio_expression_input = 9; + + // End interaction helps to end the exploration. EndExplorationInstance end_exploration = 10; } } @@ -422,7 +452,9 @@ message Outcome { } // Structure corresponds to StateStructureVersion. +// Structure for a single hint message Hint { + // Hint data. SubtitledHtml hint_content = 1; } @@ -445,7 +477,14 @@ message Solution { } // Structure corresponds to StateStructureVersion. +// Structure for a single misconception, after parsing the original string received from the backend: +// https://github.com/oppia/oppia/blob/896466ae8bdd34641ea2e0031a5b9fa4243a3de7/core/templates/pages/ +// exploration-editor-page/editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 message Misconception { + + // Skill ID parsed from the misconception. string skill_id = 1; + + // Misconception ID parsed from the misconception. string misconception_id = 2; } diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index 11d7bfe..c8cafde 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -8,51 +8,100 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.v1.structure"; option java_multiple_files = true; +// Structure for a single topic summary. message TopicSummary { TopicSummaryStructureVersion structure_version = 1; + // The id of the topic summary. string id = 2; + + // The name of the topic summary. string name = 3; + + // The description of the topic summary. string description = 4; + + // Topic summary size can be repesent in one of the download_type. oneof download_type { + + // Downloade size of the topic summary. int32 download_size_bytes = 5; + + // Size of the TopicSummary to update the current topic. int32 update_size_bytes = 6; } + + // All story summaries related to the TopicSummaryStructureVersion. repeated StorySummary story_summaries = 7; + + // All subtopic indexes related to the TopicSummaryStructureVersion. repeated int32 subtopic_indexes = 8; + + // Thumbnail of the topic related to the TopicSummaryStructureVersion. Thumbnail thumbnail = 9; // TODO + + // Boolean to check if the topic is published or not. bool is_published = 10; + int32 content_version = 11; } // Proto version corresponds to TopicSummaryStructureVersion. message StorySummary { + + // The id of the story summary. string id = 1; + + // The title of the story summary. string title = 2; + + // The description of the story summary. string description = 3; + + // The thumbnail of the story summary. Thumbnail thumbnail = 4; // TODO + + // All the chapters related to this story summary. repeated ChapterSummary chapters = 5; + int32 content_version = 6; } // Proto version corresponds to TopicSummaryStructureVersion. message ChapterSummary { + + // Thumbnail of the chapter. Thumbnail thumbnail = 1; // TODO + + // The title of the chapter. string title = 2; + + // The id of the exploration associated to this chapter. string exploration_id = 3; + int32 content_version = 4; } // Proto version corresponds to TopicSummaryStructureVersion. message SubtopicSummary { + + // The index of the subtopic summary. int32 index = 1; + + // All the skill associated to this subtopic summary. repeated SkillSummary skill_summaries = 2; + int32 content_version = 3; } // Proto version corresponds to TopicSummaryStructureVersion. message SkillSummary { + + // The id of the skill summary. string id = 1; + + // The name of the skill summary. string name = 2; + int32 content_version = 4; } From fa1182227ea2305f0c5019f9db1b1807234ec791 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 13 Aug 2021 12:13:41 +0530 Subject: [PATCH 14/51] java package match proto package --- proto/v1/api/android.proto | 2 +- proto/v1/structure/concept_card.proto | 2 +- proto/v1/structure/exploration.proto | 2 +- proto/v1/structure/image.proto | 2 +- proto/v1/structure/languages.proto | 2 +- proto/v1/structure/objects.proto | 2 +- proto/v1/structure/question.proto | 2 +- proto/v1/structure/revision_card.proto | 2 +- proto/v1/structure/state.proto | 2 +- proto/v1/structure/topic_summary.proto | 2 +- proto/v1/structure/versions.proto | 2 +- 11 files changed, 11 insertions(+), 11 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index a813d53..6a29f6f 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -9,7 +9,7 @@ import "proto/v1/structure/revision_card.proto"; import "proto/v1/structure/topic_summary.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.api"; +option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; message TopicListRequest { diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index 3318af6..daa400a 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -6,7 +6,7 @@ import "proto/v1/structure/image.proto"; import "proto/v1/structure/languages.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure of the single concept card that can be displayed for a specific skill. diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 8eb8958..4f97bf2 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -6,7 +6,7 @@ import "proto/v1/structure/image.proto"; import "proto/v1/structure/state.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure for a single exploration. diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 0ad6247..3d2895b 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -4,7 +4,7 @@ package org.oppia.proto.v1.structure; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure for the single thumbnail. diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 2205244..244f9c5 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -4,7 +4,7 @@ package org.oppia.proto.v1.structure; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure corresponds to LanguageStructuresVersion. diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index c95c817..8b3cfa4 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure of the single Fraction. diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 7460c91..0cdf864 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -6,7 +6,7 @@ import "proto/v1/structure/image.proto"; import "proto/v1/structure/state.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure of the single question. diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 3d4de81..020dc1c 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -6,7 +6,7 @@ import "proto/v1/structure/image.proto"; import "proto/v1/structure/languages.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Corresponds to a revision card that can be displayed for a specific subtopic. diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 45eada3..11864d8 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -6,7 +6,7 @@ import "proto/v1/structure/languages.proto"; import "proto/v1/structure/objects.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure for a single state diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index c8cafde..cd91ee4 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -5,7 +5,7 @@ package org.oppia.proto.v1.structure; import "proto/v1/structure/image.proto"; import "proto/v1/structure/versions.proto"; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Structure for a single topic summary. diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto index e440f2b..31c8379 100644 --- a/proto/v1/structure/versions.proto +++ b/proto/v1/structure/versions.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -option java_package = "org.oppia.v1.structure"; +option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; message TopicSummaryStructureVersion { From cdf7150ee2f537aa3a9fec90a86669e03113a1b9 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 13 Aug 2021 12:16:22 +0530 Subject: [PATCH 15/51] LanguageStructuresVersion to LanguageProtosVersion --- README.md | 2 +- proto/v1/api/android.proto | 2 +- proto/v1/structure/languages.proto | 26 +++++++++++++------------- proto/v1/structure/versions.proto | 2 +- 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 6de2b54..587d587 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Note that one aspect of this is a bit complicated: some of the substructures are - ExplorationStructureVersion - QuestionStructureVersion - StateStructureVersion -- LanguageStructuresVersion +- LanguageProtosVersion - ImageStructureVersion #### A note on interaction versioning diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 6a29f6f..d254305 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -74,7 +74,7 @@ message ClientCompatibilityContext { org.oppia.proto.v1.structure.ExplorationStructureVersion exploration_structure_version = 4; org.oppia.proto.v1.structure.QuestionStructureVersion question_structure_version = 5; org.oppia.proto.v1.structure.StateStructureVersion state_structure_version = 6; - org.oppia.proto.v1.structure.LanguageStructuresVersion language_structures_version = 7; + org.oppia.proto.v1.structure.LanguageProtosVersion language_proto_version = 7; org.oppia.proto.v1.structure.ImageStructureVersion thumbnail_structure_version = 8; } diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 244f9c5..59d28b5 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -7,7 +7,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. enum LanguageCode { LANGUAGE_CODE_UNSPECIFIED = 0; ENGLISH = 1; @@ -20,7 +20,7 @@ enum LanguageCode { // Strucutre of the single subtitled html. message SubtitledHtml { - LanguageStructuresVersion structure_version = 1; + LanguageProtosVersion structure_version = 1; // Id of the content whomsoever corresponds to SubtitledHtml. string content_id = 2; @@ -31,19 +31,19 @@ message SubtitledHtml { // Strucutre of the single recorded voiceover. message RecordedVoiceovers { - LanguageStructuresVersion structure_version = 1; + LanguageProtosVersion structure_version = 1; - // All the voiceover corresponds to the LanguageStructuresVersion. + // All the voiceover corresponds to the LanguageProtosVersion. repeated VoiceoverContentMapping voiceover_language_mapping = 2; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message VoiceoverContentMapping { LanguageCode language_code = 1; map voiceover_content_mapping = 2; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message Voiceover { // File name of the voiceover. @@ -57,17 +57,17 @@ message Voiceover { } message WrittenTranslations { - LanguageStructuresVersion structure_version = 1; + LanguageProtosVersion structure_version = 1; repeated WrittenTranslationContentMapping translation_language_mapping = 2; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslationContentMapping { LanguageCode language_code = 1; map translation_content_mapping = 2; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslation { oneof data_format { @@ -85,22 +85,22 @@ message WrittenTranslation { } } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslatableHtml { string translation = 1; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslatableUnicode { string translation = 1; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslatableSetOfNormalizedString { repeated string translation = 1; } -// Structure corresponds to LanguageStructuresVersion. +// Structure corresponds to LanguageProtosVersion. message WrittenTranslatableSetOfUnicodeString { repeated string translation = 1; } diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto index 31c8379..c10c8b2 100644 --- a/proto/v1/structure/versions.proto +++ b/proto/v1/structure/versions.proto @@ -30,7 +30,7 @@ message StateStructureVersion { int32 version = 1; } -message LanguageStructuresVersion { +message LanguageProtosVersion { int32 version = 1; } From 0231af89fe2414d36e8242506ee08b45ecfddcea Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 17 Aug 2021 18:38:04 +0530 Subject: [PATCH 16/51] added docs --- README.md | 46 ++++--- proto/v1/api/BUILD | 5 +- proto/v1/api/android.proto | 37 +++--- proto/v1/structure/concept_card.proto | 20 +-- proto/v1/structure/exploration.proto | 11 +- proto/v1/structure/image.proto | 10 +- proto/v1/structure/languages.proto | 34 ++--- proto/v1/structure/question.proto | 14 +- proto/v1/structure/revision_card.proto | 2 +- proto/v1/structure/state.proto | 176 ++++++++++++++++++++----- proto/v1/structure/topic_summary.proto | 41 +++--- proto/v1/structure/versions.proto | 24 ++-- 12 files changed, 275 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index 587d587..2ba2933 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,36 @@ # oppia-proto-api -Published required API for the Oppia backend. +Published common proto API for the Oppia server/client. -## Versioning -Versioning starts getting a bit complicated when considering the backend VersionedModels, the model structures themselves, schema structures, proto structures, the API, snapshots of the API, and other things. To try and keep things simple, this design intends to define a _separate_ set of versions that are specific to this API. How these map to Oppia backend's many versions is an implementation detail not actually relevant to this design. +This API governs the transfer of data between the Oppia Python server and the Android app. -### API version -The API itself is versioned and has separate releases. To keep things simple, it has a major & minor version (e.g. 1.0). The major version is represented directly in the directory structure (e.g. 'v1') since the repository could, in the future, house multiple major versions (which is necessary for the backend to maintain long-term backward compatibility with older API versions). The major version is only incremented if a breaking change must be introduced into the API (generally this will only come when we want to make substantial changes to the API/redesign it). +### API Versions +Each version of this API is formatted as a major & minor version (e.g. 1.0) and corresponds to a separate release. -The API's minor version essentially counts the number of releases that major version has been changed. This means we increment the minor version anytime we make a compatible change to the API, and then release it. The main benefit of having distinct releases is it allows the backend & frontends to opt into taking on a particular version of the API. Due to the backward/forward interoperability nature of protobuf, it's unlikely there will ever be an incompatibility so long as structure versions are respected (see below), and even in those cases there should be potential for graceful failures. Note that the minor version is only ever represented in the release numbers and never in code form since it only serves the purpose of cataloging. +- The major version is represented directly in the directory structure (e.g. 'v1'), and is only incremented if a breaking change must be introduced into the API. (Note that this repository might house multiple major versions, in order to maintain long-term backward compatibility with older API versions.) +- The minor version is incremented whenever a compatible change to the API is released. It is only ever represented in the release numbers, and never in code form. -### Content versions -Content versions are meant to be the version of the entity itself corresponding to a particular structure (such as a topic, skill, or exploration). These are used to track whether there are content updates for a particular structure. These are expected to map exactly to the versions stored in the corresponding structure's VersionedModel in the backend, but how this versioning behaves is up to the backend so long as it's monotonically increasing and positive. +Because protobuf is backward/forward interoperable, incompatibilities are unlikely as long as proto versions are respected (though, even in those cases, there should be potential for graceful failures). -### Structure versions -Structure versions correspond to groups of proto structures themselves. These are unique versions to the proto structures and are **not** shared with schema structure versions in the backend. Generally, these only need to be incremented when a proto structure is updated in such a way that the default data will break existing logical assumptions (thus requiring a data migration). Proto structures should never be updated in an incompatible way (without incrementing the major version--see the API version section above), but sometimes data migrations are necessary and these versions help track when those need to occur. Unlike schema versions in the backend, these are likely to not increment as often since most proto changes can be safely ignored by older clients. +### Content Versions +Content versions represent the version of the corresponding entity instance (e.g. a topic, skill, or exploration). These are used to track whether a particular structure has content updates. They map to the versions stored in the corresponding structure's VersionedModel in the backend. -Note that one aspect of this is a bit complicated: some of the substructures are shared across high-level structures (such as SubtitledHtml, or other language-based substructures). To ensure these are properly tracked, some substructures are grouped into their own combined version to track changes. The following are the list of structure types whose versions are tracked: -- TopicSummaryStructureVersion -- RevisionCardStructureVersion -- ConceptCardStructureVersion -- ExplorationStructureVersion -- QuestionStructureVersion -- StateStructureVersion -- LanguageProtosVersion -- ImageStructureVersion +### Proto Versions +Proto versions correspond to the proto structures defined in this repository. They only need to be incremented when a proto structure is updated in such a way that the default data will break existing logical assumptions (thus requiring a data migration). Such upgrades should always happen in a compatible way (except for major API version upgrades -- see the "API Version" section above). + +Two notes: -#### A note on interaction versioning -I did want to briefly note that it was discovered during the creation of this PR & structure versions that separate versioning for interactions is not actually needed since, per the strong typing of State's substructures, the structures of individual interactions & how they relate to the exploration/question experience is implied as part of State's structure version. This does not mean the backend won't need additional version tracking for interactions in order to compute compatibility with specific proto State structure versions, but it does serendipitously simplify version tracking at the sub-State level a bit. +1. Some proto versions correspond to **groups** of substructures (such as SubtitledHtml, or other language-based substructures), because these substructures are shared across high-level structures. +2. There is no need to version interactions separately. This is because their structure and how they relate to the exploration/question experience is implied as part of State's structure version. + +The following are the list of structure types whose versions are tracked: +- TopicSummaryProtoVersion +- RevisionCardProtoVersion +- ConceptCardProtoVersion +- ExplorationProtoVersion +- QuestionProtoVersion +- StateProtoVersion +- LanguageProtosVersion +- ImageProtoVersion ## Support If you have any feature requests or bug reports, please log them on our [issue tracker](https://github.com/oppia/oppia-proto-api/issues/new?title=Describe%20your%20feature%20request%20or%20bug%20report%20succinctly&body=If%20you%27d%20like%20to%20propose%20a%20feature,%20describe%20what%20you%27d%20like%20to%20see.%0A%0AIf%20you%27re%20reporting%20a%20bug,%20please%20be%20sure%20to%20include%20the%20expected%20behaviour,%20the%20observed%20behaviour,%20and%20steps%20to%20reproduce%20the%20problem.%20Console%20copy-pastes%20and%20any%20background%20on%20the%20environment%20would%20also%20be%20helpful.%0A%0AThanks!). diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD index 02a7a11..c0061b9 100644 --- a/proto/v1/api/BUILD +++ b/proto/v1/api/BUILD @@ -1,8 +1,9 @@ """ This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. -The proto_library() rule creates a proto file library for the android API proto file to be used in multiple languages. +The proto_library() rule creates a proto file library for the android API +proto file to be used in multiple languages. The java_lite_proto_library() rule takes in a proto_library target and generates Java code. -The java_proto_library() rule takes in a proto_library target and generate Java code. +The java_proto_library() rule takes in a proto_library target and generates Java code. """ load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index d254305..3f5a35a 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -13,7 +13,7 @@ option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; message TopicListRequest { - TopicListRequestResponseStructureVersion structure_version = 1; + TopicListRequestResponseProtoVersion proto_version = 1; ClientContext client_context = 2; ClientCompatibilityContext compatibility_context = 3; @@ -21,14 +21,14 @@ message TopicListRequest { } message TopicListResponse { - TopicListRequestResponseStructureVersion structure_version = 1; + TopicListRequestResponseProtoVersion proto_version = 1; // All topic summaries that are newer & compatible with the client. repeated org.oppia.proto.v1.structure.TopicSummary topic_summaries = 2; } message TopicContentRequest { - TopicContentRequestResponseStructureVersion structure_version = 1; + TopicContentRequestResponseProtoVersion proto_version = 1; ClientContext client_context = 2; repeated DownloadRequestStructureIdentifier identifiers = 3; @@ -36,17 +36,18 @@ message TopicContentRequest { } message TopicContentResponse { - TopicContentRequestResponseStructureVersion structure_version = 1; + TopicContentRequestResponseProtoVersion proto_version = 1; repeated DownloadResult download_results = 2; - // Structure corresponds to TopicContentRequestResponseStructureVersion. + // Structure corresponds to TopicContentRequestResponseProtoVersion. message DownloadResult { DownloadRequestStructureIdentifier identifier = 1; oneof structure_type { - // Indicates that the request corresponding to this particular identifier was skipped and suggested to retry by the Oppia backend. - // Note that the presence of this value in the oneof is sufficient to indicate its state, and its actual value does not matter. + // Indicates that the request corresponding to this particular identifier was skipped + // and suggested to retry by the Oppia backend. Note that the presence of this value in the + // oneof is sufficient to indicate its state, and its actual value does not matter. bool skipped = 2; org.oppia.proto.v1.structure.RevisionCard revision_card = 3; org.oppia.proto.v1.structure.ConceptCard concept_card = 4; @@ -56,7 +57,7 @@ message TopicContentResponse { } } - // Structure corresponds to TopicContentRequestResponseStructureVersion. + // Structure corresponds to TopicContentRequestResponseProtoVersion. message QuestionIdList { repeated string question_ids = 1; } @@ -68,14 +69,14 @@ message ClientContext { } message ClientCompatibilityContext { - org.oppia.proto.v1.structure.TopicSummaryStructureVersion topic_summary_structure_version = 1; - org.oppia.proto.v1.structure.RevisionCardStructureVersion revision_card_structure_version = 2; - org.oppia.proto.v1.structure.ConceptCardStructureVersion concept_card_structure_version = 3; - org.oppia.proto.v1.structure.ExplorationStructureVersion exploration_structure_version = 4; - org.oppia.proto.v1.structure.QuestionStructureVersion question_structure_version = 5; - org.oppia.proto.v1.structure.StateStructureVersion state_structure_version = 6; + org.oppia.proto.v1.structure.TopicSummaryProtoVersion topic_summary_proto_version = 1; + org.oppia.proto.v1.structure.RevisionCardProtoVersion revision_card_proto_version = 2; + org.oppia.proto.v1.structure.ConceptCardProtoVersion concept_card_proto_version = 3; + org.oppia.proto.v1.structure.ExplorationProtoVersion exploration_proto_version = 4; + org.oppia.proto.v1.structure.QuestionProtoVersion question_proto_version = 5; + org.oppia.proto.v1.structure.StateProtoVersion state_proto_version = 6; org.oppia.proto.v1.structure.LanguageProtosVersion language_proto_version = 7; - org.oppia.proto.v1.structure.ImageStructureVersion thumbnail_structure_version = 8; + org.oppia.proto.v1.structure.ImageProtoVersion thumbnail_proto_version = 8; } message ClientDownloadStateContext { @@ -95,7 +96,7 @@ message ClientDownloadStateContext { repeated DownloadState current_downloads = 1; } -// This structure's version corresponds to TopicContentRequestResponseStructureVersion. +// This structure's version corresponds to TopicContentRequestResponseProtoVersion. message DownloadRequestStructureIdentifier { oneof structure_type { org.oppia.proto.v1.structure.SubtopicId revision_card_id = 1; @@ -106,10 +107,10 @@ message DownloadRequestStructureIdentifier { } } -message TopicListRequestResponseStructureVersion { +message TopicListRequestResponseProtoVersion { int32 version = 1; } -message TopicContentRequestResponseStructureVersion { +message TopicContentRequestResponseProtoVersion { int32 version = 1; } diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index daa400a..b743ff1 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,37 +9,39 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure of the single concept card that can be displayed for a specific skill. +// Proto of the single concept card that can be displayed for a specific skill. message ConceptCard { - ConceptCardStructureVersion structure_version = 1; + ConceptCardProtoVersion proto_version = 1; // The ID corresponding to the skill this concept is representing. string skill_id = 2; - // The skill's description that can help provide context on what content is being reviewed. + //A human-readable description for the skill. string description = 3; - // The core explanation of the skill being reviewed. + // The explanation of the skill that is shown in the concept card. SubtitledHtml explanation = 4; // A list of worked examples to present to the learner. repeated WorkedExample worked_examples = 5; - // Recorded audio to play for each SubtitledHtml in this concept card. + // The recorded audio to play SubtitledHTML subfields of this concept card. RecordedVoiceovers recorded_voiceovers = 6; - // Translations for each SubtitledHtml in this concept card. + // The translations of SubtitledHTML subfields of this concept card. WrittenTranslations written_translations = 7; + // The list of all images that are included within SubtitledHTML and WorkedExample + // subfields of this concept card. ReferencedImageList referenced_image_list = 8; - // Proto version corresponds to ConceptCardStructureVersion. + // The worked example is an example of question and answer shown in a concept card. message WorkedExample { - // Question of the worked example in the SubtitledHtml format. + // The question for this worked example. SubtitledHtml question = 1; - // Explanation of the worked example in the SubtitledHtml format. + // The explanation for how to solve this worked example. SubtitledHtml explanation = 2; } } diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 4f97bf2..b057c36 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,9 +9,9 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure for a single exploration. +// Proto of a single exploration. message Exploration { - ExplorationStructureVersion structure_version = 1; + ExplorationProtoVersion proto_version = 1; // The ID of the exploration. string id = 2; @@ -19,14 +19,15 @@ message Exploration { // The title of the exploration. string title = 3; - // The name of the state which initialize the exploration. + // The name of the initial state of the exploration. string init_state_name = 4; - // Mapping from a state name to a state object + // The mapping from state names to state objects. map states = 5; - // The version of the exploration. + // The version of the contents of this exploration. int32 content_version = 6; + // A list of all the images consists of this exploration. ReferencedImageList referenced_image_list = 7; } diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 3d2895b..ea2df37 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,19 +7,19 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure for the single thumbnail. +// Proto representing a single thumbnail image. message Thumbnail { - ImageStructureVersion structure_version = 1; + ImageProtoVersion proto_version = 1; - // Name of the thumbnail file. + // The name of the thumbnail file. string filename = 2; - // Background color of the thumbnail to use it explicitly in case of required for blurring the image. + // A background color of the thumbnail image. int32 background_color_rgb = 3; } message ReferencedImageList { - ImageStructureVersion structure_version = 1; + ImageProtoVersion proto_version = 1; repeated string referenced_image_filenames = 2; } diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 59d28b5..06693c9 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -17,23 +17,25 @@ enum LanguageCode { BRAZILIAN_PORTUGUESE = 5; } - -// Strucutre of the single subtitled html. +// NOTE: Update LanguageProtosVersion if the structure of this proto is modified. +// Proto representing a block of (subtitled) HTML. message SubtitledHtml { - LanguageProtosVersion structure_version = 1; + LanguageProtosVersion protos_version = 1; - // Id of the content whomsoever corresponds to SubtitledHtml. + // The content ID for this SubtitledHtml. This is unique within a State. string content_id = 2; - // Html format data of the content whomsoever corresponds to SubtitledHtml. + // The HTML content of the SubtitledHtml. string html = 3; } -// Strucutre of the single recorded voiceover. +// NOTE: Update LanguageProtosVersion if the structure of this proto is modified. +// Structure of the recorded voiceovers. message RecordedVoiceovers { - LanguageProtosVersion structure_version = 1; + LanguageProtosVersion protos_version = 1; - // All the voiceover corresponds to the LanguageProtosVersion. + // A mapping from language codes to voiceover bundles (which map individual content IDs + // to their voiceovers). repeated VoiceoverContentMapping voiceover_language_mapping = 2; } @@ -46,18 +48,18 @@ message VoiceoverContentMapping { // Structure corresponds to LanguageProtosVersion. message Voiceover { - // File name of the voiceover. + // The file name of the voiceover. string filename = 1; - // Size of voiceover file. + // The size of the voiceover file, in bytes. int32 file_size_bytes = 2; - // Duration of voiceover. + // The duration of the voiceover, in seconds. float duration_secs = 3; } message WrittenTranslations { - LanguageProtosVersion structure_version = 1; + LanguageProtosVersion protos_version = 1; repeated WrittenTranslationContentMapping translation_language_mapping = 2; } @@ -71,16 +73,16 @@ message WrittenTranslationContentMapping { message WrittenTranslation { oneof data_format { - // Html format data of the translation. + // The translation for an HTML string. WrittenTranslatableHtml translatable_html = 1; - // Unicode format data of the translation. + // The translation for a unicode string. WrittenTranslatableUnicode translatable_unicode = 2; - // Set of normalized string of the translation. + // The translation for a set of normalized strings. WrittenTranslatableSetOfNormalizedString translatable_set_of_normalized_string = 3; - // Set of unicode string of the translation. + // The translation for a set of unicode strings. WrittenTranslatableSetOfUnicodeString translatable_set_of_unicode_string = 4; } } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 0cdf864..efc5dba 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,20 +9,22 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure of the single question. +// Structure of a single question. message Question { - QuestionStructureVersion structure_version = 1; + QuestionProtoVersion proto_version = 1; - - // Id of the question. + // The ID of the question. string id = 2; - // Question state is the name of the state to which this question belongs. + // The State object that makes up the main part of the question. State question_state = 3; - // All the skill ids which belongs to this question. + // The full list of skill IDs linked to this question. repeated string linked_skill_ids = 4; + // The version of the contents of this question. int32 content_version = 5; + + // The list of all images that are included within SubtitledHTML subfields of this question. ReferencedImageList referenced_image_list = 6; } diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 020dc1c..ecd8aa0 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -11,7 +11,7 @@ option java_multiple_files = true; // Corresponds to a revision card that can be displayed for a specific subtopic. message RevisionCard { - RevisionCardStructureVersion structure_version = 1; + RevisionCardProtoVersion proto_version = 1; SubtopicId id = 2; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 11864d8..b01ded6 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,63 +9,63 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure for a single state +// Structure for a single State. message State { - StateStructureVersion structure_version = 1; + StateProtoVersion proto_version = 1; - // Content of the state. + // The explanation of the state. SubtitledHtml content = 2; - // Interactions of the state. + // The interactions of the state. InteractionInstance interaction = 3; - // Recorded Voiceovers of the state. + // The recorded voiceovers of the state. RecordedVoiceovers recorded_voiceovers = 4; - // Written Translations of the state. + // The written translations of the state. WrittenTranslations written_translations = 5; } -// Structure corresponds to StateStructureVersion. +// Structure for the interaction. message InteractionInstance { - // Different type of interactions. + // The different types of interaction. oneof interaction_type { - // Continue interaction. + // The interaction that takes the form of a simple Continue button. ContinueInstance continue = 1; - // Fraction input interaction. + // The interaction for fraction input. FractionInputInstance fraction_input = 2; - // Single item selection interaction. + // The interaction for item selection input. ItemSelectionInputInstance item_selection_input = 3; - // Multiple choice selection interaction. + // The interaction for multiple item selection input. MultipleChoiceInputInstance multiple_choice_input = 4; - // Numeric input interaction. + // The interaction for number input. NumericInputInstance numeric_input = 5; - // Text input interaction. + // The interaction for text input. TextInputInstance text_input = 6; - // Drag and drop type interaction. + // The interaction for drag and drop sorting. DragAndDropSortInputInstance drag_and_drop_sort_input = 7; - // Image region click interaction. + // The interaction allowing multiple-choice selection on an image. ImageClickInputInstance image_click_input = 8; - // Ratio input interaction. + // The interaction for ration input. RatioExpressionInputInstance ratio_expression_input = 9; - // End interaction helps to end the exploration. + // The interaction that allows the exploration to end. EndExplorationInstance end_exploration = 10; } } // Answer type: none (N/A since no answers are submitted for this interaction). -// Structure corresponds to StateStructureVersion. +// Structure of the continue instance. message ContinueInstance { CustomizationArgs customization_args = 1; Outcome default_outcome = 2; @@ -74,6 +74,7 @@ message ContinueInstance { // solutions. Users cannot receive hints since only one answer is possible // (clicking the button). + // Structure of the customization args of continue instance. message CustomizationArgs { // Note that while the continue interaction has a default button text // defined, it's not used in the app since the default string needs to come @@ -83,68 +84,137 @@ message ContinueInstance { } // Answer type: Fraction. -// Structure corresponds to StateStructureVersion. +// Structure of the fraction input interaction. message FractionInputInstance { + + // A set of arguments to customize the fraction instance. CustomizationArgs customization_args = 1; + + // repeated AnswerGroup answer_groups = 2; + + // A default arguments which shown in the output of the fraction instance. Outcome default_outcome = 3; + + // A list of hints in the fraction instance. repeated Hint hints = 4; + + // The solution of the fraction instance. Solution solution = 5; + // Structure of the customization args of the fraction instance. message CustomizationArgs { + + // The fraction is in simplest form or not. bool requires_simplest_form = 1; + + // The fraction allow to be in improper fraction. bool allow_improper_fractions = 2; + + // The fraction contains non zero integer part or not. bool allow_nonzero_integer_part = 3; + + // The custom arguments for fraction instance. SubtitledHtml custom_placeholder = 4; } + + // Structure of the solution of the fraction instance. message Solution { BaseSolution base_solution = 1; Fraction correct_answer = 2; } + + // Structure of the answer group of the fraction instance. message AnswerGroup { BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the fraction instance. repeated RuleSpec rule_specs = 2; } + + // Structure of the rule spec of the fraction instance. message RuleSpec { + + // Different rules which can be applied on the fraction instance. oneof rule_type { + + // A rule to check the fraction is equal to the fraction input. IsExactlyEqualToSpec is_exactly_equal_to = 1; + + // A rule to check the fraction is equivalent to the fraction input. IsEquivalentToSpec is_equivalent_to = 2; + + // A rule to check the fraction is equivalent and in the simplest form to the fraction input. IsEquivalentToAndInSimplestFormSpec is_equivalent_to_and_in_simplest_form = 3; + + // A rule to check the fraction is less than the fraction input. IsLessThanSpec is_less_than = 4; + + // A rule to check the fraction is greater than the fraction input. IsGreaterThanSpec is_greater_than = 5; + + // A rule to check the numerator of fraction is equal to the fraction input. HasNumeratorEqualToSpec has_numerator_equal_to = 6; + + // A rule to check the denominator of fraction is equal to the fraction input. HasDenominatorEqualToSpec has_denominator_equal_to = 7; + + // A rule to check the integer of fraction is equal to the fraction input. HasIntegerPartEqualToSpec has_integer_part_equal_to = 8; + + // A rule to check fraction has no fractional part to the fraction input. HasNoFractionalPartSpec has_no_fractional_part = 9; + + // A rule to check fraction has no fractional part equal to the fraction input. HasFractionalPartExactlyEqualToSpec has_fractional_part_exactly_equal_to = 10; } + + // Structure of the exactly equal rule check. message IsExactlyEqualToSpec { Fraction input = 1; } + + // Structure of the equivalent rule check. message IsEquivalentToSpec { Fraction input = 1; } + + // Structure of the equivalent and simple form rule check. message IsEquivalentToAndInSimplestFormSpec { Fraction input = 1; } + + // Structure of the less than rule check. message IsLessThanSpec { Fraction input = 1; } + + // Structure of the greater than rule check. message IsGreaterThanSpec { Fraction input = 1; } + + // Structure of the numerator equality rule check. message HasNumeratorEqualToSpec { int32 input = 1; } + + // Structure of the denominator equality rule check. message HasDenominatorEqualToSpec { uint32 input = 1; } + + // Structure of the integer part rule check. message HasIntegerPartEqualToSpec { int32 input = 1; } + + // Structure of the no fraction input rule check. message HasNoFractionalPartSpec { // No inputs for this rule spec. } + + // Structure of the fraction part exactly equality rule check. message HasFractionalPartExactlyEqualToSpec { Fraction input = 1; } @@ -152,40 +222,79 @@ message FractionInputInstance { } // Answer type: SetOfTranslatableHtmlContentIds. -// Structure corresponds to StateStructureVersion. +// Structure of the item selection input interaction. message ItemSelectionInputInstance { + + // A set of arguments to customize the item selection input instance. CustomizationArgs customization_args = 1; + + // repeated AnswerGroup answer_groups = 2; + + // A default arguments which shown in the output of the item selection input instance. Outcome default_outcome = 3; + + // A list of hints in the item selection input instance. repeated Hint hints = 4; // Item selection does not support solutions. + // Structure of the customization args of the item selection input instance. message CustomizationArgs { + + // The minimum number of items allowed for selection. int32 min_allowable_selection_count = 1; + + // The maximum number of items allowed for selection. int32 max_allowable_selection_count = 2; + + // The list of selectable items. repeated SubtitledHtml choices = 3; } + + // Structure of a single answer group. message AnswerGroup { BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the item selection instance. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the item selection instance. message RuleSpec { + + // A different type of rules for the item selection input instance. oneof rule_type { + + // A rule to check the equality. EqualsSpec equals = 1; + + // A rule to check atleast one item selected. ContainsAtLeastOneOfSpec contains_at_least_one_of = 2; + + // A rule to check non of the item is selected. DoesNotContainAtLeastOneOfSpec does_not_contain_at_least_one_of = 3; + + // A rule to check the propoer subset. IsProperSubsetOfSpec is_proper_subset_of = 4; } + + // Structure of the equal rule check. message EqualsSpec { SetOfTranslatableHtmlContentIds input = 1; } + + // Structure of atleast one item selection rule check. message ContainsAtLeastOneOfSpec { SetOfTranslatableHtmlContentIds input = 1; } + + // Structure of non of the item selection rule check. message DoesNotContainAtLeastOneOfSpec { SetOfTranslatableHtmlContentIds input = 1; } + + // Structure of proper subset of item selection rule check. message IsProperSubsetOfSpec { SetOfTranslatableHtmlContentIds input = 1; } @@ -193,7 +302,7 @@ message ItemSelectionInputInstance { } // Answer type: non-negative int (uint32). -// Structure corresponds to StateStructureVersion. +// Structure of the multiple choice input interaction. message MultipleChoiceInputInstance { CustomizationArgs customization_args = 1; repeated AnswerGroup answer_groups = 2; @@ -220,7 +329,7 @@ message MultipleChoiceInputInstance { } // Answer type: real (double). -// Structure corresponds to StateStructureVersion. +// Structure of the number input interaction. message NumericInputInstance { repeated AnswerGroup answer_groups = 1; Solution solution = 2; @@ -274,7 +383,7 @@ message NumericInputInstance { } // Answer type: normalized string (string). -// Structure corresponds to StateStructureVersion. +// Structure of the text input interaction. message TextInputInstance { CustomizationArgs customization_args = 1; repeated AnswerGroup answer_groups = 2; @@ -317,7 +426,7 @@ message TextInputInstance { } // Answer type: ListOfSetsOfTranslatableHtmlContentIds. -// Structure corresponds to StateStructureVersion. +// Structure of the drag and drop sort input interaction. message DragAndDropSortInputInstance { CustomizationArgs customization_args = 1; repeated AnswerGroup answer_groups = 2; @@ -362,7 +471,7 @@ message DragAndDropSortInputInstance { } // Answer type: ClickOnImage. -// Structure corresponds to StateStructureVersion. +// Structure of the image selection input interaction. message ImageClickInputInstance { CustomizationArgs customization_args = 1; repeated AnswerGroup answer_groups = 2; @@ -389,7 +498,7 @@ message ImageClickInputInstance { } // Answer type: RatioExpression. -// Structure corresponds to StateStructureVersion. +// Structure of the ratio input interaction. message RatioExpressionInputInstance { CustomizationArgs customization_args = 1; repeated AnswerGroup answer_groups = 2; @@ -428,7 +537,7 @@ message RatioExpressionInputInstance { } // Answer type: none (N/A since no answers are submitted for this interaction). -// Structure corresponds to StateStructureVersion. +// Structure of a single end exploration type interaction. message EndExplorationInstance { // No answers can be submitted to the end exploration, so there are neither // answer groups nor solutions. The interaction does have customization @@ -438,20 +547,18 @@ message EndExplorationInstance { } // Common fields for all answer groups. -// Structure corresponds to StateStructureVersion. message BaseAnswerGroup { Outcome outcome = 1; Misconception tagged_skill_misconception = 2; } -// Structure corresponds to StateStructureVersion. +// Structure of the outcome of any interaction. message Outcome { string destination_state = 1; SubtitledHtml feedback = 2; bool labelled_as_correct = 3; } -// Structure corresponds to StateStructureVersion. // Structure for a single hint message Hint { // Hint data. @@ -459,13 +566,11 @@ message Hint { } // Common fields for all solutions. -// Structure corresponds to StateStructureVersion. message BaseSolution { SubtitledHtml explanation = 1; } // Convenience collection object for all potential types of solutions. -// Structure corresponds to StateStructureVersion. message Solution { oneof interaction_type { FractionInputInstance.Solution fraction_instance_solution = 1; @@ -476,15 +581,14 @@ message Solution { } } -// Structure corresponds to StateStructureVersion. // Structure for a single misconception, after parsing the original string received from the backend: // https://github.com/oppia/oppia/blob/896466ae8bdd34641ea2e0031a5b9fa4243a3de7/core/templates/pages/ // exploration-editor-page/editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 message Misconception { - // Skill ID parsed from the misconception. + // The id of the skill. string skill_id = 1; - // Misconception ID parsed from the misconception. + // The id of the misconception. string misconception_id = 2; } diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index cd91ee4..d127c55 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -10,7 +10,7 @@ option java_multiple_files = true; // Structure for a single topic summary. message TopicSummary { - TopicSummaryStructureVersion structure_version = 1; + TopicSummaryProtoVersion proto_version = 1; // The id of the topic summary. string id = 2; @@ -21,32 +21,33 @@ message TopicSummary { // The description of the topic summary. string description = 4; - // Topic summary size can be repesent in one of the download_type. + // The size of the topic summary can be repesented in one of the download types. oneof download_type { - // Downloade size of the topic summary. + // The downloadable size of the topic summary, in bytes. int32 download_size_bytes = 5; - // Size of the TopicSummary to update the current topic. + // The update size of the topic summary, in bytes. int32 update_size_bytes = 6; } - // All story summaries related to the TopicSummaryStructureVersion. + // A list of StorySummary related to this TopicSummary. repeated StorySummary story_summaries = 7; - // All subtopic indexes related to the TopicSummaryStructureVersion. + // A list of indexes of all the subtopic related to the TopicSummary. repeated int32 subtopic_indexes = 8; - // Thumbnail of the topic related to the TopicSummaryStructureVersion. + // A thubmnail image of this TopicSummary. Thumbnail thumbnail = 9; // TODO - // Boolean to check if the topic is published or not. + // This TopicSummary is ready to present to the learner or not. bool is_published = 10; + // The version of the contents of this TopicSummary. int32 content_version = 11; } -// Proto version corresponds to TopicSummaryStructureVersion. +// Structure of a single story summary. message StorySummary { // The id of the story summary. @@ -58,43 +59,46 @@ message StorySummary { // The description of the story summary. string description = 3; - // The thumbnail of the story summary. + // The thumbnail image of the story summary. Thumbnail thumbnail = 4; // TODO - // All the chapters related to this story summary. + // All the chapters of this story summary. repeated ChapterSummary chapters = 5; + // The version of the contents of this story summary. int32 content_version = 6; } -// Proto version corresponds to TopicSummaryStructureVersion. +// Structure of a single chapter summary. message ChapterSummary { - // Thumbnail of the chapter. + // The thumbnail image of this chapter summary. Thumbnail thumbnail = 1; // TODO - // The title of the chapter. + // The title of the chapter summary. string title = 2; - // The id of the exploration associated to this chapter. + // The id of the exploration to which this ChapterSummary is associated. string exploration_id = 3; + // The version of the contents of this chapter summary. int32 content_version = 4; } -// Proto version corresponds to TopicSummaryStructureVersion. +// Structure of a single subtopic summary. message SubtopicSummary { // The index of the subtopic summary. int32 index = 1; - // All the skill associated to this subtopic summary. + // All the skills of this subtopic summary. repeated SkillSummary skill_summaries = 2; + // The version of the contents of this subtopic summary. int32 content_version = 3; } -// Proto version corresponds to TopicSummaryStructureVersion. +// Structure of a single skill summary. message SkillSummary { // The id of the skill summary. @@ -103,5 +107,6 @@ message SkillSummary { // The name of the skill summary. string name = 2; + // The version of the contents of this skill summary. int32 content_version = 4; } diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto index c10c8b2..b394164 100644 --- a/proto/v1/structure/versions.proto +++ b/proto/v1/structure/versions.proto @@ -5,35 +5,43 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -message TopicSummaryStructureVersion { +// The version of the TopicSummary proto structure. +message TopicSummaryProtoVersion { int32 version = 1; } -message RevisionCardStructureVersion { +// The version of the RevisionCard proto structure. +message RevisionCardProtoVersion { int32 version = 1; } -message ConceptCardStructureVersion { +// The version of the ConceptCard proto structure. +message ConceptCardProtoVersion { int32 version = 1; } -message ExplorationStructureVersion { +// The version of the Exploration proto structure. +message ExplorationProtoVersion { int32 version = 1; } -message QuestionStructureVersion { +// The version of the Question proto structure. +message QuestionProtoVersion { int32 version = 1; } -// This version implies interaction compatibility since interactions are tightly defined in the structures. -message StateStructureVersion { +// This version implies interaction compatibility since interactions are tightly defined +// in the structures. The version of the State prot structure. +message StateProtoVersion { int32 version = 1; } +// The version of the Language proto structure. message LanguageProtosVersion { int32 version = 1; } -message ImageStructureVersion { +// The version of the Image proto structure. +message ImageProtoVersion { int32 version = 1; } From ab70643f17a4092a0616a56d7024ed38eecdff22 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 17 Aug 2021 18:43:26 +0530 Subject: [PATCH 17/51] added note --- proto/v1/structure/concept_card.proto | 3 ++- proto/v1/structure/exploration.proto | 1 + proto/v1/structure/image.proto | 2 ++ proto/v1/structure/objects.proto | 2 +- proto/v1/structure/question.proto | 1 + proto/v1/structure/revision_card.proto | 1 + proto/v1/structure/state.proto | 1 + proto/v1/structure/topic_summary.proto | 1 + 8 files changed, 10 insertions(+), 2 deletions(-) diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index b743ff1..460d70a 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto of the single concept card that can be displayed for a specific skill. +// NOTE: Update ConceptCardProtoVersion if the structure of this proto is modified. +// Proto of a single concept card that can be displayed for a specific skill. message ConceptCard { ConceptCardProtoVersion proto_version = 1; diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index b057c36..689791f 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,6 +9,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update ExplorationProtoVersion if the structure of this proto is modified. // Proto of a single exploration. message Exploration { ExplorationProtoVersion proto_version = 1; diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index ea2df37..3adc5a9 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,6 +7,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. // Proto representing a single thumbnail image. message Thumbnail { ImageProtoVersion proto_version = 1; @@ -18,6 +19,7 @@ message Thumbnail { int32 background_color_rgb = 3; } +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. message ReferencedImageList { ImageProtoVersion proto_version = 1; diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index 8b3cfa4..c3e915a 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -5,7 +5,7 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure of the single Fraction. +// Structure of a single Fraction. message Fraction { // Boolean to check if fraction is negative or not. diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index efc5dba..23506db 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,6 +9,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. // Structure of a single question. message Question { QuestionProtoVersion proto_version = 1; diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index ecd8aa0..e4b9dd4 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,6 +9,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. // Corresponds to a revision card that can be displayed for a specific subtopic. message RevisionCard { RevisionCardProtoVersion proto_version = 1; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index b01ded6..99dc6a9 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,6 +9,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update StateProtoVersion if the structure of this proto is modified. // Structure for a single State. message State { StateProtoVersion proto_version = 1; diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index d127c55..361da07 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -8,6 +8,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// NOTE: Update TopicSummaryProtoVersion if the structure of this proto is modified. // Structure for a single topic summary. message TopicSummary { TopicSummaryProtoVersion proto_version = 1; From 0b2896c16ee102101ed6b6a7612122d9c5ecca6b Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 17 Aug 2021 19:03:20 +0530 Subject: [PATCH 18/51] nit fix --- README.md | 3 ++- proto/v1/structure/concept_card.proto | 3 ++- proto/v1/structure/exploration.proto | 3 ++- proto/v1/structure/image.proto | 6 ++++-- proto/v1/structure/languages.proto | 23 +++++++++++++---------- proto/v1/structure/question.proto | 3 ++- proto/v1/structure/revision_card.proto | 3 ++- proto/v1/structure/state.proto | 3 ++- proto/v1/structure/topic_summary.proto | 3 ++- 9 files changed, 31 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 2ba2933..aea6f49 100644 --- a/README.md +++ b/README.md @@ -17,10 +17,11 @@ Content versions represent the version of the corresponding entity instance (e.g ### Proto Versions Proto versions correspond to the proto structures defined in this repository. They only need to be incremented when a proto structure is updated in such a way that the default data will break existing logical assumptions (thus requiring a data migration). Such upgrades should always happen in a compatible way (except for major API version upgrades -- see the "API Version" section above). -Two notes: +Three notes: 1. Some proto versions correspond to **groups** of substructures (such as SubtitledHtml, or other language-based substructures), because these substructures are shared across high-level structures. 2. There is no need to version interactions separately. This is because their structure and how they relate to the exploration/question experience is implied as part of State's structure version. +3. If any changes happen in the proto structure which are getting tracked, the version specified in the comment must be incremented. The following are the list of structure types whose versions are tracked: - TopicSummaryProtoVersion diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index 460d70a..85e0827 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update ConceptCardProtoVersion if the structure of this proto is modified. +// NOTE: Update ConceptCardProtoVersion if the structure of this proto is modified. The current +// version is 1. // Proto of a single concept card that can be displayed for a specific skill. message ConceptCard { ConceptCardProtoVersion proto_version = 1; diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 689791f..f490bc5 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update ExplorationProtoVersion if the structure of this proto is modified. +// NOTE: Update ExplorationProtoVersion if the structure of this proto is modified. The current +// version is 1. // Proto of a single exploration. message Exploration { ExplorationProtoVersion proto_version = 1; diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 3adc5a9..765b5aa 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,7 +7,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current +// version is 1. // Proto representing a single thumbnail image. message Thumbnail { ImageProtoVersion proto_version = 1; @@ -19,7 +20,8 @@ message Thumbnail { int32 background_color_rgb = 3; } -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current +// version is 1. message ReferencedImageList { ImageProtoVersion proto_version = 1; diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 06693c9..0a18cf7 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -7,7 +7,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure corresponds to LanguageProtosVersion. +// A list of language code. enum LanguageCode { LANGUAGE_CODE_UNSPECIFIED = 0; ENGLISH = 1; @@ -34,18 +34,18 @@ message SubtitledHtml { message RecordedVoiceovers { LanguageProtosVersion protos_version = 1; - // A mapping from language codes to voiceover bundles (which map individual content IDs + // A list of mapping from language codes to voiceover bundles (which map individual content IDs // to their voiceovers). repeated VoiceoverContentMapping voiceover_language_mapping = 2; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a voiceover content. message VoiceoverContentMapping { LanguageCode language_code = 1; map voiceover_content_mapping = 2; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a voiceover. message Voiceover { // The file name of the voiceover. @@ -58,19 +58,22 @@ message Voiceover { float duration_secs = 3; } +// Structure of the written translations. message WrittenTranslations { LanguageProtosVersion protos_version = 1; repeated WrittenTranslationContentMapping translation_language_mapping = 2; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a writtent translation content. message WrittenTranslationContentMapping { LanguageCode language_code = 1; map translation_content_mapping = 2; } -// Structure corresponds to LanguageProtosVersion. +// Structure of the written translation. message WrittenTranslation { + + // The different data format supported for transaltions. oneof data_format { // The translation for an HTML string. @@ -87,22 +90,22 @@ message WrittenTranslation { } } -// Structure corresponds to LanguageProtosVersion. +// Structure of a html string translation. message WrittenTranslatableHtml { string translation = 1; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a unicode string translation. message WrittenTranslatableUnicode { string translation = 1; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a set of normalized string transaltions. message WrittenTranslatableSetOfNormalizedString { repeated string translation = 1; } -// Structure corresponds to LanguageProtosVersion. +// Structure of a set of unicode string transaltions. message WrittenTranslatableSetOfUnicodeString { repeated string translation = 1; } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 23506db..bfce908 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. +// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. The current +// version is 1. // Structure of a single question. message Question { QuestionProtoVersion proto_version = 1; diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index e4b9dd4..70116a9 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. +// NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current +// version is 1. // Corresponds to a revision card that can be displayed for a specific subtopic. message RevisionCard { RevisionCardProtoVersion proto_version = 1; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 99dc6a9..939359f 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,7 +9,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update StateProtoVersion if the structure of this proto is modified. +// NOTE: Update StateProtoVersion if the structure of this proto is modified. The current +// version is 1. // Structure for a single State. message State { StateProtoVersion proto_version = 1; diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index 361da07..7b0f3cf 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -8,7 +8,8 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update TopicSummaryProtoVersion if the structure of this proto is modified. +// NOTE: Update TopicSummaryProtoVersion if the structure of this proto is modified. The current +// version is 1. // Structure for a single topic summary. message TopicSummary { TopicSummaryProtoVersion proto_version = 1; From 5d868e2c5a555bb78abc6a79ac1e505afc3e748a Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Wed, 18 Aug 2021 15:53:36 +0530 Subject: [PATCH 19/51] added docs --- proto/v1/api/android.proto | 2 +- proto/v1/structure/image.proto | 4 +- proto/v1/structure/objects.proto | 16 +- proto/v1/structure/revision_card.proto | 14 +- proto/v1/structure/state.proto | 309 +++++++++++++++++++++++-- proto/v1/structure/versions.proto | 16 +- 6 files changed, 313 insertions(+), 48 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 3f5a35a..c69e1d2 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -75,7 +75,7 @@ message ClientCompatibilityContext { org.oppia.proto.v1.structure.ExplorationProtoVersion exploration_proto_version = 4; org.oppia.proto.v1.structure.QuestionProtoVersion question_proto_version = 5; org.oppia.proto.v1.structure.StateProtoVersion state_proto_version = 6; - org.oppia.proto.v1.structure.LanguageProtosVersion language_proto_version = 7; + org.oppia.proto.v1.structure.LanguageProtosVersion language_protos_version = 7; org.oppia.proto.v1.structure.ImageProtoVersion thumbnail_proto_version = 8; } diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 765b5aa..dd352d4 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -13,7 +13,7 @@ option java_multiple_files = true; message Thumbnail { ImageProtoVersion proto_version = 1; - // The name of the thumbnail file. + // The name of the thumbnail image file. string filename = 2; // A background color of the thumbnail image. @@ -22,8 +22,10 @@ message Thumbnail { // NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current // version is 1. +// Proto representing a list of images. message ReferencedImageList { ImageProtoVersion proto_version = 1; + // The list of filename of all the images. repeated string referenced_image_filenames = 2; } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index c3e915a..43fad38 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -8,16 +8,16 @@ option java_multiple_files = true; // Structure of a single Fraction. message Fraction { - // Boolean to check if fraction is negative or not. + // This fraction is negative or not. bool is_negative = 1; - // Whole number of the fraction. + // The whole number of the fraction. uint32 whole_number = 2; - // Numerator of the fraction. + // The numerator of the fraction. uint32 numerator = 3; - // Denominator of the fraction. + // The denominator of the fraction. int32 denominator = 4; } @@ -81,16 +81,16 @@ message ImageWithRegions { // A string that represents a filepath which will be prefixed with '[exploration_id]/assets. string image_file_path = 1; - // All the labeled regions in this ImageWithRegions. + // All the labeled regions of the image with regions. repeated LabeledRegion labeled_regions = 2; - // A region of an image, including its shape and coordinates. + // A label used to represent a region of the image. message LabeledRegion { - // The name for the region. + // The name of the label for a region. string label = 3; - // Represents the different Region Types. + // The different types of regions. oneof region_type { // A rectangle normalized so that the coordinates are within the range [0,1]. diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 70116a9..155d503 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -11,16 +11,17 @@ option java_multiple_files = true; // NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current // version is 1. -// Corresponds to a revision card that can be displayed for a specific subtopic. +// Proto of a revision card that can be displayed for a specific subtopic. message RevisionCard { RevisionCardProtoVersion proto_version = 1; + // The id of the subtopic in which this revision card is displayed. SubtopicId id = 2; - // The title corresponding to the subtopic. + // The title of the revision card. string title = 3; - // The core explanation of the subtopic being revised. + // The content of this revision card. SubtitledHtml content = 4; // The recorded voiceovers to play for the corresponding revision card. @@ -29,13 +30,16 @@ message RevisionCard { // The written translations of the revision card. WrittenTranslations written_translations = 6; - // The thumbnail of the revision card. + // The thumbnail image of the revision card. Thumbnail thumbnail = 7; + // The list of image used in this revision card. ReferencedImageList referenced_image_list = 8; } -// This structure is shared among multiple parent structures, so it has no direct migration pathway. Changes should be carefully done, or the structure should be duplicated according to whichever structure requires alterations. +// This proto is shared among multiple parent protos, so it has no direct migration +// pathway. Changes should be carefully done, or the proto should be duplicated according +// to whichever proto requires alterations. message SubtopicId { string topic_id = 1; int32 index = 2; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 939359f..17811a6 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -15,7 +15,7 @@ option java_multiple_files = true; message State { StateProtoVersion proto_version = 1; - // The explanation of the state. + // The content of the state. SubtitledHtml content = 2; // The interactions of the state. @@ -28,10 +28,10 @@ message State { WrittenTranslations written_translations = 5; } -// Structure for the interaction. +// Structure for a single interaction. message InteractionInstance { - // The different types of interaction. + // The different types of interactions. oneof interaction_type { // The interaction that takes the form of a simple Continue button. @@ -70,6 +70,8 @@ message InteractionInstance { // Structure of the continue instance. message ContinueInstance { CustomizationArgs customization_args = 1; + + // The default outcome of the continue instance. Outcome default_outcome = 2; // Continue interactions cannot have custom answer groups, and do not support @@ -89,22 +91,22 @@ message ContinueInstance { // Structure of the fraction input interaction. message FractionInputInstance { - // A set of arguments to customize the fraction instance. + // A set of arguments to customize the fraction input. CustomizationArgs customization_args = 1; - // + // A list of answer groups of the fraction input. repeated AnswerGroup answer_groups = 2; - // A default arguments which shown in the output of the fraction instance. + // The default outcome of the fraction input. Outcome default_outcome = 3; - // A list of hints in the fraction instance. + // A list of hints in the fraction input. repeated Hint hints = 4; - // The solution of the fraction instance. + // The solution of the fraction input. Solution solution = 5; - // Structure of the customization args of the fraction instance. + // Structure of the customization args of the fraction input. message CustomizationArgs { // The fraction is in simplest form or not. @@ -116,28 +118,34 @@ message FractionInputInstance { // The fraction contains non zero integer part or not. bool allow_nonzero_integer_part = 3; - // The custom arguments for fraction instance. + // The custom placeholders for fraction input. SubtitledHtml custom_placeholder = 4; } - // Structure of the solution of the fraction instance. + // Structure of the solution of the fraction input. message Solution { + + // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; + + // The correct answer of this fraction input. Fraction correct_answer = 2; } - // Structure of the answer group of the fraction instance. + // Structure of the answer group of the fraction input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the fraction instance. + // A list of all the rules of the fraction input. repeated RuleSpec rule_specs = 2; } - // Structure of the rule spec of the fraction instance. + // Structure of the rule spec of the fraction input. message RuleSpec { - // Different rules which can be applied on the fraction instance. + // Different rules which can be applied on the fraction input. oneof rule_type { // A rule to check the fraction is equal to the fraction input. @@ -227,21 +235,21 @@ message FractionInputInstance { // Structure of the item selection input interaction. message ItemSelectionInputInstance { - // A set of arguments to customize the item selection input instance. + // A set of arguments to customize the item selection input. CustomizationArgs customization_args = 1; - // + // A list of answer groups of the item selection input. repeated AnswerGroup answer_groups = 2; - // A default arguments which shown in the output of the item selection input instance. + // The default outcome of the item selection input. Outcome default_outcome = 3; - // A list of hints in the item selection input instance. + // A list of hints in the item selection input. repeated Hint hints = 4; // Item selection does not support solutions. - // Structure of the customization args of the item selection input instance. + // Structure of the customization args of the item selection input. message CustomizationArgs { // The minimum number of items allowed for selection. @@ -254,18 +262,20 @@ message ItemSelectionInputInstance { repeated SubtitledHtml choices = 3; } - // Structure of a single answer group. + // Structure of a single answer group of item selection input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the item selection instance. + // A list of all the rules of the item selection input. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the item selection instance. + // Structure of the rules of the item selection input. message RuleSpec { - // A different type of rules for the item selection input instance. + // Different type of rules for the item selection input instance. oneof rule_type { // A rule to check the equality. @@ -306,24 +316,49 @@ message ItemSelectionInputInstance { // Answer type: non-negative int (uint32). // Structure of the multiple choice input interaction. message MultipleChoiceInputInstance { + + // A set of arguments to customize the multiple choice input. CustomizationArgs customization_args = 1; + + // A list of answer groups of the multiple choice input. repeated AnswerGroup answer_groups = 2; + + // The default outcome of the multiple choice input. Outcome default_outcome = 3; + + // The list of hints for this multiple choice input. repeated Hint hints = 4; // Multiple choice does not support solutions. + // Structure of the customization args of the multiple choice input. message CustomizationArgs { + + // A list of possible choices from the multiple items. repeated SubtitledHtml choices = 1; } + + // Structure of a single answer group of multiple choice input. message AnswerGroup { + + // A base answer group is a set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the multiple choice input. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the multiple choice input. message RuleSpec { + + // Differnt type of rules for the multiple choice input. oneof rule_type { + + // A rule to check the equality. EqualsSpec equals = 1; } + + // Structure of the equal rule check. message EqualsSpec { uint32 input = 1; } @@ -333,50 +368,97 @@ message MultipleChoiceInputInstance { // Answer type: real (double). // Structure of the number input interaction. message NumericInputInstance { + + // A list of answer groups of the numeric input. repeated AnswerGroup answer_groups = 1; Solution solution = 2; + + // The default outcome of the numeric input. Outcome default_outcome = 3; repeated Hint hints = 4; // Numeric input does not have any customization arguments. + // Structure of the solution of the numeric input. message Solution { + + // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; + + // The correct answer of this numeric input. double correct_answer = 2; } + + // Structure of a single answer group of numeric input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the numeric input. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the numeric input. message RuleSpec { + + // Different type of rules which can be applied on the numeric input. oneof rule_type { + + // A rule to check the equality. EqualsSpec equals = 1; + + // A rule to check less than a value or not. IsLessThanSpec is_less_than = 2; + + // A rule to check the greater than value or not. IsGreaterThanSpec is_greater_than = 3; + + // A rule to check the less than or equal value or not. IsLessThanOrEqualToSpec is_less_than_or_equal_to = 4; + + // A rule to check the greter than or equal value or not. IsGreaterThanOrEqualToSpec is_greater_than_or_equal_to = 5; + + // A rule to check the inclusive range. IsInclusivelyBetweenSpec is_inclusively_between = 6; + + // A rule to check the tolerance range. IsWithinToleranceSpec is_within_tolerance = 7; } + + // Structure of the equal rule check. message EqualsSpec { double input = 1; } + + // Structure of the less than rule check. message IsLessThanSpec { double input = 1; } + + // Structure of the greater than rule check. message IsGreaterThanSpec { double input = 1; } + + // Structure of the less than or equal rule check. message IsLessThanOrEqualToSpec { double input = 1; } + + // Structure of the greater than or equal rule check. message IsGreaterThanOrEqualToSpec { double input = 1; } + + // Structure of the inclusive range rule check. message IsInclusivelyBetweenSpec { double inputLowerInclusive = 1; double inputUpperInclusive = 2; } + + // Structure of the tolerance ranage rule check. message IsWithinToleranceSpec { double inputTolerance = 1; double inputComparedValue = 2; @@ -387,31 +469,64 @@ message NumericInputInstance { // Answer type: normalized string (string). // Structure of the text input interaction. message TextInputInstance { + + // A set of arguments to customize the text input instance. CustomizationArgs customization_args = 1; + + // A list of answer groups of the text input interaction instance. repeated AnswerGroup answer_groups = 2; + + // The default outcome of the text instance. Outcome default_outcome = 3; + + // A list of hints for text input instance. repeated Hint hints = 4; + + // The solution of the text input instance. Solution solution = 5; + // Structure of the customization args of the text input instance. message CustomizationArgs { + + // A placeholder value for the text input instance. SubtitledHtml placeholder = 1; + + // The number of rows for the text input instance. int32 rows = 2; } + + // Structure of the solution of the text input instance. message Solution { + + // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; + + // The correct answer of this text instance. string correct_answer = 2; } + + // Structure of a single answer group of text input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the text instance. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the text input instance. message RuleSpec { + + // Different rules which can be applied on the text input instance. oneof rule_type { EqualsSpec equals = 1; StartsWithSpec starts_with = 2; ContainsSpec contains = 3; FuzzyEqualsSpec fuzzy_equals = 4; } + + // Structure of the equal rule check. message EqualsSpec { TranslatableSetOfNormalizedString input = 1; } @@ -430,43 +545,94 @@ message TextInputInstance { // Answer type: ListOfSetsOfTranslatableHtmlContentIds. // Structure of the drag and drop sort input interaction. message DragAndDropSortInputInstance { + + // A set of arguments to customize the drag and drop sort instance. CustomizationArgs customization_args = 1; + + // A list of answer groups of the drag and drop sort input interaction instance. repeated AnswerGroup answer_groups = 2; + + // The default outcome of the drag and drop sort instance. Outcome default_outcome = 3; + + // A list of all the hints for drag and drop sort instance. repeated Hint hints = 4; + + // The solution of the drag and drop sort instance. Solution solution = 5; + // Structure of the customization args of the drag and drop sort instance. message CustomizationArgs { repeated SubtitledHtml choices = 1; bool allowMultipleItemsInSamePosition = 2; } + + // Structure of the solution of the drag and drop sort instance. message Solution { + + // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; + + // The correct answer of this drag and drop sort instance. ListOfSetsOfTranslatableHtmlContentIds correct_answer = 2; } + + // Structure of a single answer group of drag and drop sort input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the drag and drop sort instance. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the drag and drop sort instance. message RuleSpec { + + // Different rules which can be applied on the drag and drop sort instance. oneof rule_type { + + // A rule to check equal order. IsEqualToOrderingSpec is_equal_to_ordering = 1; + + // A rule to check equal order and one item at incorrect position. IsEqualToOrderingWithOneItemAtIncorrectPositionSpec is_equal_to_ordering_with_one_item_at_incorrect_position = 2; + + // A rule to check the position of an item. HasElementXAtPositionYSpec has_element_x_at_position_y = 3; + + // A rule to check the previous position of an item. HasElementXBeforeElementYSpec has_element_x_before_element_y = 4; } + + // Structure of an equal order rule. message IsEqualToOrderingSpec { ListOfSetsOfTranslatableHtmlContentIds input = 1; } + + // Structure of an equal order with one incorrect position rule. message IsEqualToOrderingWithOneItemAtIncorrectPositionSpec { ListOfSetsOfTranslatableHtmlContentIds input = 1; } + + // Structure of an item position check rule. message HasElementXAtPositionYSpec { + + // The item whose position to check. TranslatableHtmlContentId element = 1; + + // The position of the item to check. uint32 position = 2; } + + // Structure of an item previous position check rule. message HasElementXBeforeElementYSpec { + + // The previous position of an item. TranslatableHtmlContentId considered_element = 1; + + // The next element of the item. TranslatableHtmlContentId later_element = 2; } } @@ -475,24 +641,49 @@ message DragAndDropSortInputInstance { // Answer type: ClickOnImage. // Structure of the image selection input interaction. message ImageClickInputInstance { + + // A set of arguments to customize the image click input. CustomizationArgs customization_args = 1; + + // A list of answer groups of the image click input. repeated AnswerGroup answer_groups = 2; + + // The default outcome of the image click input. Outcome default_outcome = 3; + + // A list of all the hints for image click input. repeated Hint hints = 4; // Image click input doesn't yet support solutions. + // Structure of the customization args of the image click input. message CustomizationArgs { + + // An image with the regions. ImageWithRegions image_and_regions = 1; } + + // Structure of a single answer group of image selection input. message AnswerGroup { + + // A base answer group is a set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the image click input. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the image click input. message RuleSpec { + + // Different rules which can be applied on the image click input. oneof rule_type { + + // A rule to check the region availability. IsInRegionSpec is_in_region = 1; } + + // Structure of a single is in region. message IsInRegionSpec { string input_region = 1; } @@ -502,36 +693,79 @@ message ImageClickInputInstance { // Answer type: RatioExpression. // Structure of the ratio input interaction. message RatioExpressionInputInstance { + + // A set of arguments to customize the ratio expression input. CustomizationArgs customization_args = 1; + + // A list of answer groups of the ratio expression input interaction instance. repeated AnswerGroup answer_groups = 2; + + // The default outcome of the ratio expression input. Outcome default_outcome = 3; + + // A list of hints for the ratio expression input. repeated Hint hints = 4; + + // The solution of the ratio expression input. Solution solution = 5; + // Structure of the customization args of the ratio expression input. message CustomizationArgs { + + // A placeholder for the ratio expression input. SubtitledHtml placeholder = 1; + + // The number of terms in the ration expression. int32 number_of_terms = 2; } + + // Structure of the solution of the ratio expression input. message Solution { + + // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; + + // The correct answer of this ratio expression input. RatioExpression correct_answer = 2; } + + // Structure of a single answer group of ratio expression input. message AnswerGroup { + + // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; + + // A list of all the rules of the ratio expression input. repeated RuleSpec rule_specs = 2; } + + // Structure of the rules of the ratio expression input. message RuleSpec { + + // Different rules which can be applied on the ratio expression input. oneof rule_type { + + // A rule to check the equality. EqualsSpec equals = 1; + + // A rule to check the equivalent. IsEquivalentSpec is_equivalent = 2; + + // A rule to check the number of terms. HasNumberOfTermsEqualToSpec has_number_of_terms_equal_to = 3; } + + // Structure of the equal rule check. message EqualsSpec { RatioExpression input = 1; } + + // Structure of the equivalent rule check. message IsEquivalentSpec { RatioExpression input = 1; } + + // Structure of the numer of terms equal rule check. message HasNumberOfTermsEqualToSpec { uint32 input_term_count = 1; } @@ -550,35 +784,60 @@ message EndExplorationInstance { // Common fields for all answer groups. message BaseAnswerGroup { + + // An outcome is a common way of reponse for all interactions. Outcome outcome = 1; + + // The misconception which is tagged to a single skill. Misconception tagged_skill_misconception = 2; } // Structure of the outcome of any interaction. message Outcome { + + // The name of the next state. string destination_state = 1; + + // The feedback is the reponse for the learners input in interaction. SubtitledHtml feedback = 2; + + // The label to mark the answer correct. bool labelled_as_correct = 3; } // Structure for a single hint message Hint { - // Hint data. + + // The content of the hint. SubtitledHtml hint_content = 1; } // Common fields for all solutions. message BaseSolution { + + // The explanation of the solution. SubtitledHtml explanation = 1; } // Convenience collection object for all potential types of solutions. message Solution { + + // The different type of interactions existed in an exploration. oneof interaction_type { + + // The interaction to allow fraction inputs. FractionInputInstance.Solution fraction_instance_solution = 1; + + // The interaction to allow numeric inputs. NumericInputInstance.Solution numeric_input_instance_solution = 2; + + // The interaction to allow text inputs. TextInputInstance.Solution text_input_instance_solution = 3; + + // The interaction to allow drag and drop inputs. DragAndDropSortInputInstance.Solution drag_and_drop_sort_input_instance_solution = 4; + + // The interaction to allow ratio inputs. RatioExpressionInputInstance.Solution ratio_expression_input_instance_solution = 5; } } diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto index b394164..704ca99 100644 --- a/proto/v1/structure/versions.proto +++ b/proto/v1/structure/versions.proto @@ -5,43 +5,43 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// The version of the TopicSummary proto structure. +// The version of the TopicSummary proto. message TopicSummaryProtoVersion { int32 version = 1; } -// The version of the RevisionCard proto structure. +// The version of the RevisionCard proto. message RevisionCardProtoVersion { int32 version = 1; } -// The version of the ConceptCard proto structure. +// The version of the ConceptCard proto. message ConceptCardProtoVersion { int32 version = 1; } -// The version of the Exploration proto structure. +// The version of the Exploration proto. message ExplorationProtoVersion { int32 version = 1; } -// The version of the Question proto structure. +// The version of the Question proto. message QuestionProtoVersion { int32 version = 1; } // This version implies interaction compatibility since interactions are tightly defined -// in the structures. The version of the State prot structure. +// in the structures. The version of the State proto. message StateProtoVersion { int32 version = 1; } -// The version of the Language proto structure. +// The version of the Language proto. message LanguageProtosVersion { int32 version = 1; } -// The version of the Image proto structure. +// The version of the Image proto. message ImageProtoVersion { int32 version = 1; } From 0b937e336b3604e5e759633966cc2180b265d8f3 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Wed, 18 Aug 2021 17:39:00 +0530 Subject: [PATCH 20/51] nit fix --- proto/v1/structure/state.proto | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 17811a6..9239ad5 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -454,13 +454,21 @@ message NumericInputInstance { // Structure of the inclusive range rule check. message IsInclusivelyBetweenSpec { + + // lower value in inclusive range. double inputLowerInclusive = 1; + + // upper value in inclusive range. double inputUpperInclusive = 2; } // Structure of the tolerance ranage rule check. message IsWithinToleranceSpec { + + // Input tolerance value. double inputTolerance = 1; + + // Tolerance value to compare. double inputComparedValue = 2; } } @@ -520,9 +528,17 @@ message TextInputInstance { // Different rules which can be applied on the text input instance. oneof rule_type { + + // A rule to check equal text. EqualsSpec equals = 1; + + // A rule to check starting text of input. StartsWithSpec starts_with = 2; + + // A rule to check a substring of the input text. ContainsSpec contains = 3; + + // A rule to check the input text equals. FuzzyEqualsSpec fuzzy_equals = 4; } @@ -530,12 +546,18 @@ message TextInputInstance { message EqualsSpec { TranslatableSetOfNormalizedString input = 1; } + + // Structure of the rule to check starting text. message StartsWithSpec { TranslatableSetOfNormalizedString input = 1; } + + // Structureof the rule to check the substring of the text. message ContainsSpec { TranslatableSetOfNormalizedString input = 1; } + + // Structure of the rule to check text equality. message FuzzyEqualsSpec { TranslatableSetOfNormalizedString input = 1; } @@ -563,7 +585,11 @@ message DragAndDropSortInputInstance { // Structure of the customization args of the drag and drop sort instance. message CustomizationArgs { + + // A list of choice for drag and drop. repeated SubtitledHtml choices = 1; + + // Items are allowed at same position or not. bool allowMultipleItemsInSamePosition = 2; } From 5ceec822d9f67b0bd071e610b4ad6dd1f69c0e38 Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 23 Aug 2021 02:07:13 -0700 Subject: [PATCH 21/51] Update most docstrings. --- proto/v1/api/android.proto | 74 ++++++++++++++++++++++--- proto/v1/structure/concept_card.proto | 14 +++-- proto/v1/structure/exploration.proto | 14 +++-- proto/v1/structure/image.proto | 8 ++- proto/v1/structure/languages.proto | 54 ++++++++++++------ proto/v1/structure/objects.proto | 77 +++++++++++++++----------- proto/v1/structure/question.proto | 9 +-- proto/v1/structure/revision_card.proto | 23 +++++--- proto/v1/structure/state.proto | 74 ++++++++++++------------- 9 files changed, 226 insertions(+), 121 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index c69e1d2..7cacea0 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -12,42 +12,69 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; +// The proto request made to the server to get the list of topics which are +// available for download. message TopicListRequest { + // The common proto version defining this request/response pair. TopicListRequestResponseProtoVersion proto_version = 1; + // Details about the Android app client that is making the request. ClientContext client_context = 2; + // Details about the latest proto versions that this Android client can support. ClientCompatibilityContext compatibility_context = 3; + // TODO: Fill this in. ClientDownloadStateContext download_context = 4; } +// The expected proto response from the server when provided with a +// TopicListRequest. message TopicListResponse { + // The common proto version defining this request/response pair. TopicListRequestResponseProtoVersion proto_version = 1; - // All topic summaries that are newer & compatible with the client. + // A list of the latest topic summaries that are newer than the ones stored + // on the client, but still compatible with the client. repeated org.oppia.proto.v1.structure.TopicSummary topic_summaries = 2; } +// The proto request made to the server to get the latest still-compatible +// content for specific topics. message TopicContentRequest { + // The common proto version defining this request/response pair. TopicContentRequestResponseProtoVersion proto_version = 1; + // Details about the Android app client that is making the request. ClientContext client_context = 2; + // The IDs of the entities making up the topic whose data is to be fetched. repeated DownloadRequestStructureIdentifier identifiers = 3; + // The maximum payload size that the server should furnish as a single + // download operation. This is only a request, and may not be honoured by the + // server (which will only adhere to this field on a best-effort basis). int32 requested_max_payload_size = 4; } +// The expected proto response from the server when provided with a +// TopicContentRequest. message TopicContentResponse { + // The common proto version defining this request/response pair. TopicContentRequestResponseProtoVersion proto_version = 1; + // A list of the individual items to be downloaded. repeated DownloadResult download_results = 2; - // Structure corresponds to TopicContentRequestResponseProtoVersion. + // The result of downloading a specific asset. This may either contain the result of the + // download, or an indication that the download was skipped. + // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto + // is modified. The current version is 1. message DownloadResult { + // The entity type and ID corresponding to this download. DownloadRequestStructureIdentifier identifier = 1; oneof structure_type { - // Indicates that the request corresponding to this particular identifier was skipped - // and suggested to retry by the Oppia backend. Note that the presence of this value in the - // oneof is sufficient to indicate its state, and its actual value does not matter. + // The presence of this value indicates that the request corresponding to this + // particular identifier was skipped and suggested to retry by the Oppia backend. + // Note that the presence of this value in the oneof is sufficient to indicate + // its state; its actual value does not matter. bool skipped = 2; org.oppia.proto.v1.structure.RevisionCard revision_card = 3; org.oppia.proto.v1.structure.ConceptCard concept_card = 4; @@ -57,28 +84,47 @@ message TopicContentResponse { } } - // Structure corresponds to TopicContentRequestResponseProtoVersion. + // A list of question IDs corresponding to the topic. + // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto + // is modified. The current version is 1. message QuestionIdList { + // The list of question IDs. repeated string question_ids = 1; } } +// TODO: Add docs. message ClientContext { + // TODO: Add doc and clarify name. string version_name = 1; + // TODO: Add doc and clarify name. int64 version_code = 2; } +// Information about the latest proto versions that the client can support. +// TODO: Clarify whether, if a client can support version N, this means it can support +// versions 1 to N, or only version N. If neither of these, then we might need a +// "from ... to" range for each field, rather than a single version. message ClientCompatibilityContext { + // The latest proto version for topic summaries that the client can support. org.oppia.proto.v1.structure.TopicSummaryProtoVersion topic_summary_proto_version = 1; + // The latest proto version for revision cards that the client can support. org.oppia.proto.v1.structure.RevisionCardProtoVersion revision_card_proto_version = 2; + // The latest proto version for concept cards that the client can support. org.oppia.proto.v1.structure.ConceptCardProtoVersion concept_card_proto_version = 3; + // The latest proto version for explorations that the client can support. org.oppia.proto.v1.structure.ExplorationProtoVersion exploration_proto_version = 4; + // The latest proto version for questions that the client can support. org.oppia.proto.v1.structure.QuestionProtoVersion question_proto_version = 5; + // The latest proto version for states that the client can support. org.oppia.proto.v1.structure.StateProtoVersion state_proto_version = 6; + // The latest proto version for language-related protos that the client can support. org.oppia.proto.v1.structure.LanguageProtosVersion language_protos_version = 7; + // The latest proto version for images that the client can support. org.oppia.proto.v1.structure.ImageProtoVersion thumbnail_proto_version = 8; } +// TODO: Document this fully. message ClientDownloadStateContext { message DownloadState { int32 content_version = 1; @@ -86,8 +132,8 @@ message ClientDownloadStateContext { string topic_id = 2; org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; string concept_card_id = 4; - string story_id = 5; - string exploration_id = 6; + string story_id = 5; + string exploration_id = 6; string question_id = 7; string skill_id = 8; } @@ -96,21 +142,31 @@ message ClientDownloadStateContext { repeated DownloadState current_downloads = 1; } -// This structure's version corresponds to TopicContentRequestResponseProtoVersion. +// The type and ID of a specific asset that is being downloaded. +// NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto +// is modified. message DownloadRequestStructureIdentifier { oneof structure_type { + // The ID of the revision card ("subtopic") to be downloaded. org.oppia.proto.v1.structure.SubtopicId revision_card_id = 1; + // The ID of the concept card to be downloaded. string concept_card_id = 2; + // The ID of the exploration to be downloaded. string exploration_id = 3; + // The skill ID whose associated questions are to be downloaded. + // TODO: Clarify difference between this and concept_card_id above (field 2). string question_list_skill_id = 4; + // The ID of the question to be downloaded. string question_id = 5; } } +// The only currently-supported proto version for the TopicListRequestResponse. message TopicListRequestResponseProtoVersion { int32 version = 1; } +// The only currently-supported proto version for the TopicContentRequestResponse. message TopicContentRequestResponseProtoVersion { int32 version = 1; } diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index 85e0827..b27a3e9 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,10 +9,11 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single concept card that can be displayed for a specific skill. // NOTE: Update ConceptCardProtoVersion if the structure of this proto is modified. The current // version is 1. -// Proto of a single concept card that can be displayed for a specific skill. message ConceptCard { + // The proto version defining the internal structure of this concept card proto message. ConceptCardProtoVersion proto_version = 1; // The ID corresponding to the skill this concept is representing. @@ -27,17 +28,18 @@ message ConceptCard { // A list of worked examples to present to the learner. repeated WorkedExample worked_examples = 5; - // The recorded audio to play SubtitledHTML subfields of this concept card. + // The recorded voiceovers for SubtitledHtml subfields of this concept card. RecordedVoiceovers recorded_voiceovers = 6; - // The translations of SubtitledHTML subfields of this concept card. + // The translations of SubtitledHtml subfields of this concept card. WrittenTranslations written_translations = 7; - // The list of all images that are included within SubtitledHTML and WorkedExample - // subfields of this concept card. + // The list of all images that are included within SubtitledHtml subfields of this + // concept card. ReferencedImageList referenced_image_list = 8; - // The worked example is an example of question and answer shown in a concept card. + // Each worked example provides a sample question and answer for the student to read + // and learn from. message WorkedExample { // The question for this worked example. diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index f490bc5..59933e4 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,27 +9,29 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single exploration. // NOTE: Update ExplorationProtoVersion if the structure of this proto is modified. The current // version is 1. -// Proto of a single exploration. message Exploration { + // The proto version defining the internal structure of this exploration proto message. ExplorationProtoVersion proto_version = 1; // The ID of the exploration. string id = 2; - + // The title of the exploration. string title = 3; - + // The name of the initial state of the exploration. string init_state_name = 4; - + // The mapping from state names to state objects. map states = 5; - // The version of the contents of this exploration. + // The version of the contents of this exploration. (This corresponds to the 'version' + // field on the server.) int32 content_version = 6; - // A list of all the images consists of this exploration. + // A list of all the images contained in SubtitledHtml subfields of this exploration. ReferencedImageList referenced_image_list = 7; } diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index dd352d4..9a5ef65 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,16 +7,17 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single thumbnail image. // NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current // version is 1. -// Proto representing a single thumbnail image. message Thumbnail { + // The proto version defining the internal structure of this image proto message. ImageProtoVersion proto_version = 1; // The name of the thumbnail image file. string filename = 2; - // A background color of the thumbnail image. + // The background color to be shown behind the thumbnail image. int32 background_color_rgb = 3; } @@ -24,8 +25,9 @@ message Thumbnail { // version is 1. // Proto representing a list of images. message ReferencedImageList { + // The proto version defining the internal structure of this list of images. ImageProtoVersion proto_version = 1; - // The list of filename of all the images. + // The list of filenames of all the images in the list. repeated string referenced_image_filenames = 2; } diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 0a18cf7..c8fdf08 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -7,8 +7,9 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// A list of language code. +// A list of language codes supported by the Android app. enum LanguageCode { + // TODO: Add docstring to explain why this is needed and when it should be used. LANGUAGE_CODE_UNSPECIFIED = 0; ENGLISH = 1; ARABIC = 2; @@ -17,9 +18,11 @@ enum LanguageCode { BRAZILIAN_PORTUGUESE = 5; } +// Proto message representing a block of (subtitled) HTML. // NOTE: Update LanguageProtosVersion if the structure of this proto is modified. -// Proto representing a block of (subtitled) HTML. message SubtitledHtml { + // The proto version defining the internal structure of this proto message. + // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. LanguageProtosVersion protos_version = 1; // The content ID for this SubtitledHtml. This is unique within a State. @@ -29,25 +32,30 @@ message SubtitledHtml { string html = 3; } +// Proto message representing recorded voiceovers. // NOTE: Update LanguageProtosVersion if the structure of this proto is modified. -// Structure of the recorded voiceovers. message RecordedVoiceovers { + // The proto version defining the internal structure of this proto message. + // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. LanguageProtosVersion protos_version = 1; - // A list of mapping from language codes to voiceover bundles (which map individual content IDs - // to their voiceovers). + // A list of mappings from language codes to voiceover bundles (which each map individual + // SubtitledHtml content IDs to their voiceovers in that language). repeated VoiceoverContentMapping voiceover_language_mapping = 2; } -// Structure of a voiceover content. +// Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a +// particular language. message VoiceoverContentMapping { + // The language code that this mapping is for. LanguageCode language_code = 1; + + // The mapping of content IDs to their corresponding voiceover files. map voiceover_content_mapping = 2; } -// Structure of a voiceover. +// Proto message representing a specific voiceover file. message Voiceover { - // The file name of the voiceover. string filename = 1; @@ -58,24 +66,32 @@ message Voiceover { float duration_secs = 3; } -// Structure of the written translations. +// Proto message representing a set of written translations. message WrittenTranslations { + // The proto version defining the internal structure of this proto message. + // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. LanguageProtosVersion protos_version = 1; + + // A list of mappings from language codes to written translations (which each map + // individual SubtitledHtml content IDs to their written translations in that language). repeated WrittenTranslationContentMapping translation_language_mapping = 2; } -// Structure of a writtent translation content. +// Proto message mapping SubtitledHtml fields to their corresponding written translations +// in a particular language. message WrittenTranslationContentMapping { + // The language code that this mapping is for. LanguageCode language_code = 1; + + // The mapping of content IDs to their corresponding written translations. map translation_content_mapping = 2; } -// Structure of the written translation. +// Proto message representing a single written translation. message WrittenTranslation { - // The different data format supported for transaltions. + // The data format of the source material for this translation. oneof data_format { - // The translation for an HTML string. WrittenTranslatableHtml translatable_html = 1; @@ -90,22 +106,26 @@ message WrittenTranslation { } } -// Structure of a html string translation. +// Proto message representing the translation of a single HTML string. message WrittenTranslatableHtml { string translation = 1; } -// Structure of a unicode string translation. +// Proto message representing the translation of a single unicode string. message WrittenTranslatableUnicode { string translation = 1; } -// Structure of a set of normalized string transaltions. +// Proto message representing the translation of a set of normalized strings. Note that +// such translations have a variable number of strings, the number of which may be +// different from the number of strings in the original set. message WrittenTranslatableSetOfNormalizedString { repeated string translation = 1; } -// Structure of a set of unicode string transaltions. +// Proto message representing the translation of a set of unicode strings. Note that such +// translations have a variable number of strings, the number of which may be different +// from the number of strings in the original set. message WrittenTranslatableSetOfUnicodeString { repeated string translation = 1; } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index 43fad38..cba4633 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -5,13 +5,13 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure of a single Fraction. +// Proto message representing a single fraction or mixed number. message Fraction { - // This fraction is negative or not. + // Whether the fraction is negative. bool is_negative = 1; - // The whole number of the fraction. + // The whole number part of the fraction. uint32 whole_number = 2; // The numerator of the fraction. @@ -21,84 +21,99 @@ message Fraction { int32 denominator = 4; } -// Corresponds to a single string value as designated by a content ID. The value for this -// translatable content will be present in the written translations structure of the containing -// State. +// Proto representing a single content ID for an HTML field. This content ID is used to +// map HTML fields to their corresponding translations and voiceovers (see e.g. the +// WrittenTranslations substructure of the corresponding State). message TranslatableHtmlContentId { + // The content ID for the HTML field, which is unique within a given State. string content_id = 1; } -// Corresponds to a set of TranslatableHtmlContentIds. +// Proto representing a set of TranslatableHtmlContentIds. message SetOfTranslatableHtmlContentIds { + // The set of content IDs. repeated TranslatableHtmlContentId content_ids = 1; } -// Corresponds to a list of SetOfTranslatableHtmlContentIds. +// Proto representing a list of SetOfTranslatableHtmlContentIds. message ListOfSetsOfTranslatableHtmlContentIds { + // The sets of content IDs. repeated SetOfTranslatableHtmlContentIds content_id_lists = 1; } -// 2-Dimensional Point for interaction type image region selection. +// Proto representing a 2D point for the ImageRegion interaction type. message Point2d { - // x axis. + // Relative x-coordinate of the point within the image. This lies within the + // range [0, 1] and measures horizontal distance (with the left boundary of the image + // as the origin). double x = 1; - // y axis. + // Relative y-coordinate of the point within the image. This lies within the + // range [0, 1] and measures vertical distance (with the top boundary of the image + // as the origin). double y = 2; } - -// Click action on image for for interaction type image region selection. +// Proto representing the location of a click on an image. This is for the ImageRegion +// interaction type. message ClickOnImage { - // X,Y coordinates where user clicked on image. + // The relative coordinates of the point where the user clicked on the image. Point2d click_position = 1; - // All the selected regions on the image. + // All the selected regions on the image. repeated string clicked_regions = 2; } -// Structure containing a ratio object for eg - [1,2,3] for 1:2:3. +// Proto representing a ratio object in list form, e.g. [1,2,3] for 1:2:3. message RatioExpression { - // List of components in a ratio. It's expected that list should have more than - // 1 element. + // List of components in the ratio. The list is expected to have more than one element. repeated uint32 components = 1; } -// Corresponds to a set of normalized strings which are described in this structure, but which have -// replacement translations findable in the written translations structure of the containing State. +// Proto representing a translatable set of normalized strings. This arises in the context of +// rules, which may check the learner's answer against one of a given set of strings. The +// corresponding replacement strings for a different language can be found in the WrittenTranslations +// structure of the containing State. message TranslatableSetOfNormalizedString { + // The content ID corresponding to this set of normalized strings. string content_id = 1; - // All the normalized strings. + // The set of normalized strings to be translated as a whole. repeated string normalized_strings = 2; } -// An image overlaid with labeled regions. +// Proto representing an image that is overlaid with labeled regions. message ImageWithRegions { - // A string that represents a filepath which will be prefixed with '[exploration_id]/assets. + // The filepath of the image, which will be prefixed with '[exploration_id]/assets'. string image_file_path = 1; - // All the labeled regions of the image with regions. + // The labeled regions of this image. repeated LabeledRegion labeled_regions = 2; - // A label used to represent a region of the image. + // Proto representing a labeled region of the image. message LabeledRegion { - - // The name of the label for a region. + // The name of the region's label. string label = 3; - // The different types of regions. + // The type of the region. oneof region_type { - - // A rectangle normalized so that the coordinates are within the range [0,1]. + // A rectangle that is normalized so that its boundary coordinates are within the range + // [0,1], where 0 corresponds to one end of the image and 1 to the other. NormalizedRectangle2d normalized_rectangle_2d = 1; } + + // Proto representing a 2D rectangle defined using normalized coordinates relative to the + // image. The origin of the coordinate system is at the top left of the image. The x-coordinate + // measures horizontal distance (to the right), and the y-coordinate measures vertical distance + // (downwards). message NormalizedRectangle2d { - // Origin is top-left, increasing x is to the right, increasing y is down. + // The top-left corner of the rectangle, in normalized coordinates. Point2d upper_left = 1; + + // The bottom-right corner of the rectangle, in normalized coordinates. Point2d lower_right = 2; } } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index bfce908..258425b 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,24 +9,25 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single question. // NOTE: Update QuestionProtoVersion if the structure of this proto is modified. The current // version is 1. -// Structure of a single question. message Question { + // The proto version defining the internal structure of this question proto message. QuestionProtoVersion proto_version = 1; // The ID of the question. string id = 2; - // The State object that makes up the main part of the question. + // The State object that makes up the main part of this question. State question_state = 3; - // The full list of skill IDs linked to this question. + // The list of all skill IDs that are linked to this question. repeated string linked_skill_ids = 4; // The version of the contents of this question. int32 content_version = 5; - // The list of all images that are included within SubtitledHTML subfields of this question. + // The list of all images that are included within SubtitledHtml subfields of this question. ReferencedImageList referenced_image_list = 6; } diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 155d503..c13b046 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,10 +9,12 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single revision card that can be displayed for a specific +// subtopic. // NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current // version is 1. -// Proto of a revision card that can be displayed for a specific subtopic. message RevisionCard { + // The proto version defining the internal structure of this revision card proto message. RevisionCardProtoVersion proto_version = 1; // The id of the subtopic in which this revision card is displayed. @@ -24,23 +26,28 @@ message RevisionCard { // The content of this revision card. SubtitledHtml content = 4; - // The recorded voiceovers to play for the corresponding revision card. + // The recorded voiceovers for SubtitledHtml subfields of this revision card. RecordedVoiceovers recorded_voiceovers = 5; - // The written translations of the revision card. + // The written translations for SubtitledHtml subfields of this revision card. WrittenTranslations written_translations = 6; - // The thumbnail image of the revision card. + // The thumbnail image for this revision card. Thumbnail thumbnail = 7; - // The list of image used in this revision card. + // The list of all images that are included within SubtitledHtml subfields of this + // revision card. ReferencedImageList referenced_image_list = 8; } -// This proto is shared among multiple parent protos, so it has no direct migration -// pathway. Changes should be carefully done, or the proto should be duplicated according -// to whichever proto requires alterations. +// Proto message representing a subtopic ID. +// This proto message type is shared among multiple parent protos, so it has no direct +// migration pathway. Changes should be carefully done, or the proto should be duplicated +// according to whichever proto requires alterations. message SubtopicId { + // The ID of the topic that contains this subtopic. string topic_id = 1; + + // The index of this subtopic within its parent topic. int32 index = 2; } diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 9239ad5..8f0c7e7 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,9 +9,9 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// Proto message representing a single State. // NOTE: Update StateProtoVersion if the structure of this proto is modified. The current // version is 1. -// Structure for a single State. message State { StateProtoVersion proto_version = 1; @@ -20,10 +20,10 @@ message State { // The interactions of the state. InteractionInstance interaction = 3; - + // The recorded voiceovers of the state. RecordedVoiceovers recorded_voiceovers = 4; - + // The written translations of the state. WrittenTranslations written_translations = 5; } @@ -37,7 +37,7 @@ message InteractionInstance { // The interaction that takes the form of a simple Continue button. ContinueInstance continue = 1; - // The interaction for fraction input. + // The interaction for fraction input. FractionInputInstance fraction_input = 2; // The interaction for item selection input. @@ -55,13 +55,13 @@ message InteractionInstance { // The interaction for drag and drop sorting. DragAndDropSortInputInstance drag_and_drop_sort_input = 7; - // The interaction allowing multiple-choice selection on an image. + // The interaction allowing multiple-choice selection on an image. ImageClickInputInstance image_click_input = 8; // The interaction for ration input. RatioExpressionInputInstance ratio_expression_input = 9; - // The interaction that allows the exploration to end. + // The interaction that allows the exploration to end. EndExplorationInstance end_exploration = 10; } } @@ -118,7 +118,7 @@ message FractionInputInstance { // The fraction contains non zero integer part or not. bool allow_nonzero_integer_part = 3; - // The custom placeholders for fraction input. + // The custom placeholders for fraction input. SubtitledHtml custom_placeholder = 4; } @@ -138,7 +138,7 @@ message FractionInputInstance { // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the fraction input. + // A list of all the rules of the fraction input. repeated RuleSpec rule_specs = 2; } @@ -148,31 +148,31 @@ message FractionInputInstance { // Different rules which can be applied on the fraction input. oneof rule_type { - // A rule to check the fraction is equal to the fraction input. + // A rule to check the fraction is equal to the fraction input. IsExactlyEqualToSpec is_exactly_equal_to = 1; - // A rule to check the fraction is equivalent to the fraction input. + // A rule to check the fraction is equivalent to the fraction input. IsEquivalentToSpec is_equivalent_to = 2; - // A rule to check the fraction is equivalent and in the simplest form to the fraction input. + // A rule to check the fraction is equivalent and in the simplest form to the fraction input. IsEquivalentToAndInSimplestFormSpec is_equivalent_to_and_in_simplest_form = 3; - // A rule to check the fraction is less than the fraction input. + // A rule to check the fraction is less than the fraction input. IsLessThanSpec is_less_than = 4; - // A rule to check the fraction is greater than the fraction input. + // A rule to check the fraction is greater than the fraction input. IsGreaterThanSpec is_greater_than = 5; - // A rule to check the numerator of fraction is equal to the fraction input. + // A rule to check the numerator of fraction is equal to the fraction input. HasNumeratorEqualToSpec has_numerator_equal_to = 6; - // A rule to check the denominator of fraction is equal to the fraction input. + // A rule to check the denominator of fraction is equal to the fraction input. HasDenominatorEqualToSpec has_denominator_equal_to = 7; - // A rule to check the integer of fraction is equal to the fraction input. + // A rule to check the integer of fraction is equal to the fraction input. HasIntegerPartEqualToSpec has_integer_part_equal_to = 8; - // A rule to check fraction has no fractional part to the fraction input. + // A rule to check fraction has no fractional part to the fraction input. HasNoFractionalPartSpec has_no_fractional_part = 9; // A rule to check fraction has no fractional part equal to the fraction input. @@ -268,10 +268,10 @@ message ItemSelectionInputInstance { // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the item selection input. + // A list of all the rules of the item selection input. repeated RuleSpec rule_specs = 2; } - + // Structure of the rules of the item selection input. message RuleSpec { @@ -284,29 +284,29 @@ message ItemSelectionInputInstance { // A rule to check atleast one item selected. ContainsAtLeastOneOfSpec contains_at_least_one_of = 2; - // A rule to check non of the item is selected. + // A rule to check non of the item is selected. DoesNotContainAtLeastOneOfSpec does_not_contain_at_least_one_of = 3; // A rule to check the propoer subset. IsProperSubsetOfSpec is_proper_subset_of = 4; } - // Structure of the equal rule check. + // Structure of the equal rule check. message EqualsSpec { SetOfTranslatableHtmlContentIds input = 1; } - // Structure of atleast one item selection rule check. + // Structure of atleast one item selection rule check. message ContainsAtLeastOneOfSpec { SetOfTranslatableHtmlContentIds input = 1; } - // Structure of non of the item selection rule check. + // Structure of non of the item selection rule check. message DoesNotContainAtLeastOneOfSpec { SetOfTranslatableHtmlContentIds input = 1; } - // Structure of proper subset of item selection rule check. + // Structure of proper subset of item selection rule check. message IsProperSubsetOfSpec { SetOfTranslatableHtmlContentIds input = 1; } @@ -334,7 +334,7 @@ message MultipleChoiceInputInstance { // Structure of the customization args of the multiple choice input. message CustomizationArgs { - // A list of possible choices from the multiple items. + // A list of possible choices from the multiple items. repeated SubtitledHtml choices = 1; } @@ -358,7 +358,7 @@ message MultipleChoiceInputInstance { EqualsSpec equals = 1; } - // Structure of the equal rule check. + // Structure of the equal rule check. message EqualsSpec { uint32 input = 1; } @@ -408,7 +408,7 @@ message NumericInputInstance { // A rule to check the equality. EqualsSpec equals = 1; - // A rule to check less than a value or not. + // A rule to check less than a value or not. IsLessThanSpec is_less_than = 2; // A rule to check the greater than value or not. @@ -529,7 +529,7 @@ message TextInputInstance { // Different rules which can be applied on the text input instance. oneof rule_type { - // A rule to check equal text. + // A rule to check equal text. EqualsSpec equals = 1; // A rule to check starting text of input. @@ -577,7 +577,7 @@ message DragAndDropSortInputInstance { // The default outcome of the drag and drop sort instance. Outcome default_outcome = 3; - // A list of all the hints for drag and drop sort instance. + // A list of all the hints for drag and drop sort instance. repeated Hint hints = 4; // The solution of the drag and drop sort instance. @@ -705,11 +705,11 @@ message ImageClickInputInstance { // Different rules which can be applied on the image click input. oneof rule_type { - // A rule to check the region availability. + // A rule to check the region availability. IsInRegionSpec is_in_region = 1; } - // Structure of a single is in region. + // Structure of a single is in region. message IsInRegionSpec { string input_region = 1; } @@ -741,7 +741,7 @@ message RatioExpressionInputInstance { // A placeholder for the ratio expression input. SubtitledHtml placeholder = 1; - // The number of terms in the ration expression. + // The number of terms in the ration expression. int32 number_of_terms = 2; } @@ -774,7 +774,7 @@ message RatioExpressionInputInstance { // A rule to check the equality. EqualsSpec equals = 1; - // A rule to check the equivalent. + // A rule to check the equivalent. IsEquivalentSpec is_equivalent = 2; // A rule to check the number of terms. @@ -854,16 +854,16 @@ message Solution { // The interaction to allow fraction inputs. FractionInputInstance.Solution fraction_instance_solution = 1; - // The interaction to allow numeric inputs. + // The interaction to allow numeric inputs. NumericInputInstance.Solution numeric_input_instance_solution = 2; - // The interaction to allow text inputs. + // The interaction to allow text inputs. TextInputInstance.Solution text_input_instance_solution = 3; - // The interaction to allow drag and drop inputs. + // The interaction to allow drag and drop inputs. DragAndDropSortInputInstance.Solution drag_and_drop_sort_input_instance_solution = 4; - // The interaction to allow ratio inputs. + // The interaction to allow ratio inputs. RatioExpressionInputInstance.Solution ratio_expression_input_instance_solution = 5; } } From 78d06fa1a4854c6ef9df359535f8023a63a5289b Mon Sep 17 00:00:00 2001 From: Sean Lip Date: Mon, 13 Sep 2021 21:46:08 -0700 Subject: [PATCH 22/51] Work through topic summary as well. --- proto/v1/structure/topic_summary.proto | 56 +++++++++++++------------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index 7b0f3cf..83a9004 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -14,101 +14,103 @@ option java_multiple_files = true; message TopicSummary { TopicSummaryProtoVersion proto_version = 1; - // The id of the topic summary. + // The id of the topic. string id = 2; - // The name of the topic summary. + // The name of the topic. string name = 3; - // The description of the topic summary. + // The description of the topic. string description = 4; - // The size of the topic summary can be repesented in one of the download types. + // The size of the topic summary data is represented using one of the + // download types ("download" for a fresh download, "update" for an update to + // an existing download). oneof download_type { - // The downloadable size of the topic summary, in bytes. + // The size of the topic summary download, in bytes. int32 download_size_bytes = 5; - // The update size of the topic summary, in bytes. + // The size of the topic summary update, in bytes. int32 update_size_bytes = 6; } - // A list of StorySummary related to this TopicSummary. + // A list of story summaries related to this TopicSummary. repeated StorySummary story_summaries = 7; - // A list of indexes of all the subtopic related to the TopicSummary. + // A list of all the subtopic indexes contained in this topic. repeated int32 subtopic_indexes = 8; - // A thubmnail image of this TopicSummary. + // The thumbnail image corresponding to this topic. Thumbnail thumbnail = 9; // TODO - // This TopicSummary is ready to present to the learner or not. + // Whether the corresponding topic has been published. bool is_published = 10; - // The version of the contents of this TopicSummary. + // The version of this topic's contents. int32 content_version = 11; } // Structure of a single story summary. message StorySummary { - // The id of the story summary. + // The id of the story. string id = 1; - // The title of the story summary. + // The title of the story. string title = 2; - // The description of the story summary. + // The description of the story. string description = 3; - // The thumbnail image of the story summary. + // The thumbnail image of the story. Thumbnail thumbnail = 4; // TODO - // All the chapters of this story summary. + // The summaries of all chapters in this story. repeated ChapterSummary chapters = 5; - // The version of the contents of this story summary. + // The version of this story's contents. int32 content_version = 6; } // Structure of a single chapter summary. message ChapterSummary { - // The thumbnail image of this chapter summary. + // The thumbnail image for this chapter. Thumbnail thumbnail = 1; // TODO - // The title of the chapter summary. + // The title of the chapter. string title = 2; // The id of the exploration to which this ChapterSummary is associated. string exploration_id = 3; - // The version of the contents of this chapter summary. + // The version of this chapter's contents. int32 content_version = 4; } // Structure of a single subtopic summary. message SubtopicSummary { - // The index of the subtopic summary. + // The index of the subtopic (within its correspnoding topic). int32 index = 1; - // All the skills of this subtopic summary. + // All the skills in this subtopic. repeated SkillSummary skill_summaries = 2; - // The version of the contents of this subtopic summary. + // The version of this subtopic's contents. int32 content_version = 3; } // Structure of a single skill summary. message SkillSummary { - // The id of the skill summary. + // The id of the skill. string id = 1; - // The name of the skill summary. + // The name of the skill. string name = 2; - // The version of the contents of this skill summary. - int32 content_version = 4; + // The version of this skill's contents. + int32 content_version = 3; } From ee332e2783a7f733b2af58dd83deedfc29dfb42f Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 13 Oct 2021 13:42:41 -0700 Subject: [PATCH 23/51] Clean up line comment wrapping. Lines should wrap at 100 chars for proto files. --- proto/v1/api/android.proto | 46 +++++++++--------- proto/v1/structure/concept_card.proto | 7 ++- proto/v1/structure/exploration.proto | 4 +- proto/v1/structure/image.proto | 8 ++-- proto/v1/structure/languages.proto | 22 ++++----- proto/v1/structure/objects.proto | 36 +++++++-------- proto/v1/structure/question.proto | 4 +- proto/v1/structure/revision_card.proto | 13 ++---- proto/v1/structure/state.proto | 64 +++++++++++--------------- proto/v1/structure/topic_summary.proto | 5 +- proto/v1/structure/versions.proto | 18 ++++---- 11 files changed, 104 insertions(+), 123 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 7cacea0..5f24417 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -12,8 +12,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; -// The proto request made to the server to get the list of topics which are -// available for download. +// The proto request made to the server to get the list of topics which are available for download. message TopicListRequest { // The common proto version defining this request/response pair. TopicListRequestResponseProtoVersion proto_version = 1; @@ -26,19 +25,18 @@ message TopicListRequest { ClientDownloadStateContext download_context = 4; } -// The expected proto response from the server when provided with a -// TopicListRequest. +// The expected proto response from the server when provided with a TopicListRequest. message TopicListResponse { // The common proto version defining this request/response pair. TopicListRequestResponseProtoVersion proto_version = 1; - // A list of the latest topic summaries that are newer than the ones stored - // on the client, but still compatible with the client. + // A list of the latest topic summaries that are newer than the ones stored on the client, but + // still compatible with the client. repeated org.oppia.proto.v1.structure.TopicSummary topic_summaries = 2; } -// The proto request made to the server to get the latest still-compatible -// content for specific topics. +// The proto request made to the server to get the latest still-compatible content for specific +// topics. message TopicContentRequest { // The common proto version defining this request/response pair. TopicContentRequestResponseProtoVersion proto_version = 1; @@ -47,14 +45,13 @@ message TopicContentRequest { ClientContext client_context = 2; // The IDs of the entities making up the topic whose data is to be fetched. repeated DownloadRequestStructureIdentifier identifiers = 3; - // The maximum payload size that the server should furnish as a single - // download operation. This is only a request, and may not be honoured by the - // server (which will only adhere to this field on a best-effort basis). + // The maximum payload size that the server should furnish as a single download operation. This is + // only a request, and may not be honoured by the server (which will only adhere to this field on + // a best-effort basis). int32 requested_max_payload_size = 4; } -// The expected proto response from the server when provided with a -// TopicContentRequest. +// The expected proto response from the server when provided with a TopicContentRequest. message TopicContentResponse { // The common proto version defining this request/response pair. TopicContentRequestResponseProtoVersion proto_version = 1; @@ -62,19 +59,19 @@ message TopicContentResponse { // A list of the individual items to be downloaded. repeated DownloadResult download_results = 2; - // The result of downloading a specific asset. This may either contain the result of the - // download, or an indication that the download was skipped. - // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto - // is modified. The current version is 1. + // The result of downloading a specific asset. This may either contain the result of the download, + // or an indication that the download was skipped. + // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is + // modified. The current version is 1. message DownloadResult { // The entity type and ID corresponding to this download. DownloadRequestStructureIdentifier identifier = 1; oneof structure_type { - // The presence of this value indicates that the request corresponding to this - // particular identifier was skipped and suggested to retry by the Oppia backend. - // Note that the presence of this value in the oneof is sufficient to indicate - // its state; its actual value does not matter. + // The presence of this value indicates that the request corresponding to this particular + // identifier was skipped and suggested to retry by the Oppia backend. Note that the presence + // of this value in the oneof is sufficient to indicate its state; its actual value does not + // matter. bool skipped = 2; org.oppia.proto.v1.structure.RevisionCard revision_card = 3; org.oppia.proto.v1.structure.ConceptCard concept_card = 4; @@ -85,8 +82,8 @@ message TopicContentResponse { } // A list of question IDs corresponding to the topic. - // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto - // is modified. The current version is 1. + // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is + // modified. The current version is 1. message QuestionIdList { // The list of question IDs. repeated string question_ids = 1; @@ -143,8 +140,7 @@ message ClientDownloadStateContext { } // The type and ID of a specific asset that is being downloaded. -// NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto -// is modified. +// NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is modified. message DownloadRequestStructureIdentifier { oneof structure_type { // The ID of the revision card ("subtopic") to be downloaded. diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index b27a3e9..c782c8a 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -34,12 +34,11 @@ message ConceptCard { // The translations of SubtitledHtml subfields of this concept card. WrittenTranslations written_translations = 7; - // The list of all images that are included within SubtitledHtml subfields of this - // concept card. + // The list of all images that are included within SubtitledHtml subfields of this concept card. ReferencedImageList referenced_image_list = 8; - // Each worked example provides a sample question and answer for the student to read - // and learn from. + // Each worked example provides a sample question and answer for the student to read and learn + // from. message WorkedExample { // The question for this worked example. diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 59933e4..0586834 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -28,8 +28,8 @@ message Exploration { // The mapping from state names to state objects. map states = 5; - // The version of the contents of this exploration. (This corresponds to the 'version' - // field on the server.) + // The version of the contents of this exploration. (This corresponds to the 'version' field on + // the server.) int32 content_version = 6; // A list of all the images contained in SubtitledHtml subfields of this exploration. diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 9a5ef65..26030c3 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -8,8 +8,8 @@ option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single thumbnail image. -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current -// version is 1. +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current version +// is 1. message Thumbnail { // The proto version defining the internal structure of this image proto message. ImageProtoVersion proto_version = 1; @@ -21,8 +21,8 @@ message Thumbnail { int32 background_color_rgb = 3; } -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current -// version is 1. +// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current version +// is 1. // Proto representing a list of images. message ReferencedImageList { // The proto version defining the internal structure of this list of images. diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index c8fdf08..8257334 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -44,8 +44,8 @@ message RecordedVoiceovers { repeated VoiceoverContentMapping voiceover_language_mapping = 2; } -// Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a -// particular language. +// Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a particular +// language. message VoiceoverContentMapping { // The language code that this mapping is for. LanguageCode language_code = 1; @@ -72,13 +72,13 @@ message WrittenTranslations { // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. LanguageProtosVersion protos_version = 1; - // A list of mappings from language codes to written translations (which each map - // individual SubtitledHtml content IDs to their written translations in that language). + // A list of mappings from language codes to written translations (which each map individual + // SubtitledHtml content IDs to their written translations in that language). repeated WrittenTranslationContentMapping translation_language_mapping = 2; } -// Proto message mapping SubtitledHtml fields to their corresponding written translations -// in a particular language. +// Proto message mapping SubtitledHtml fields to their corresponding written translations in a +// particular language. message WrittenTranslationContentMapping { // The language code that this mapping is for. LanguageCode language_code = 1; @@ -116,16 +116,16 @@ message WrittenTranslatableUnicode { string translation = 1; } -// Proto message representing the translation of a set of normalized strings. Note that -// such translations have a variable number of strings, the number of which may be -// different from the number of strings in the original set. +// Proto message representing the translation of a set of normalized strings. Note that such +// translations have a variable number of strings, the number of which may be different from the +// number of strings in the original set. message WrittenTranslatableSetOfNormalizedString { repeated string translation = 1; } // Proto message representing the translation of a set of unicode strings. Note that such -// translations have a variable number of strings, the number of which may be different -// from the number of strings in the original set. +// translations have a variable number of strings, the number of which may be different from the +// number of strings in the original set. message WrittenTranslatableSetOfUnicodeString { repeated string translation = 1; } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index cba4633..d85a959 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -21,9 +21,9 @@ message Fraction { int32 denominator = 4; } -// Proto representing a single content ID for an HTML field. This content ID is used to -// map HTML fields to their corresponding translations and voiceovers (see e.g. the -// WrittenTranslations substructure of the corresponding State). +// Proto representing a single content ID for an HTML field. This content ID is used to map HTML +// fields to their corresponding translations and voiceovers (see e.g. the WrittenTranslations +// substructure of the corresponding State). message TranslatableHtmlContentId { // The content ID for the HTML field, which is unique within a given State. string content_id = 1; @@ -44,19 +44,17 @@ message ListOfSetsOfTranslatableHtmlContentIds { // Proto representing a 2D point for the ImageRegion interaction type. message Point2d { - // Relative x-coordinate of the point within the image. This lies within the - // range [0, 1] and measures horizontal distance (with the left boundary of the image - // as the origin). + // Relative x-coordinate of the point within the image. This lies within the range [0, 1] and + // measures horizontal distance (with the left boundary of the image as the origin). double x = 1; - // Relative y-coordinate of the point within the image. This lies within the - // range [0, 1] and measures vertical distance (with the top boundary of the image - // as the origin). + // Relative y-coordinate of the point within the image. This lies within the range [0, 1] and + // measures vertical distance (with the top boundary of the image as the origin). double y = 2; } -// Proto representing the location of a click on an image. This is for the ImageRegion -// interaction type. +// Proto representing the location of a click on an image. This is for the ImageRegion interaction +// type. message ClickOnImage { // The relative coordinates of the point where the user clicked on the image. @@ -72,10 +70,10 @@ message RatioExpression { repeated uint32 components = 1; } -// Proto representing a translatable set of normalized strings. This arises in the context of -// rules, which may check the learner's answer against one of a given set of strings. The -// corresponding replacement strings for a different language can be found in the WrittenTranslations -// structure of the containing State. +// Proto representing a translatable set of normalized strings. This arises in the context of rules, +// which may check the learner's answer against one of a given set of strings. The corresponding +// replacement strings for a different language can be found in the WrittenTranslations structure of +// the containing State. message TranslatableSetOfNormalizedString { // The content ID corresponding to this set of normalized strings. string content_id = 1; @@ -100,13 +98,13 @@ message ImageWithRegions { // The type of the region. oneof region_type { - // A rectangle that is normalized so that its boundary coordinates are within the range - // [0,1], where 0 corresponds to one end of the image and 1 to the other. + // A rectangle that is normalized so that its boundary coordinates are within the range [0,1], + // where 0 corresponds to one end of the image and 1 to the other. NormalizedRectangle2d normalized_rectangle_2d = 1; } - // Proto representing a 2D rectangle defined using normalized coordinates relative to the - // image. The origin of the coordinate system is at the top left of the image. The x-coordinate + // Proto representing a 2D rectangle defined using normalized coordinates relative to the image. + // The origin of the coordinate system is at the top left of the image. The x-coordinate // measures horizontal distance (to the right), and the y-coordinate measures vertical distance // (downwards). message NormalizedRectangle2d { diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 258425b..e165880 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -10,8 +10,8 @@ option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single question. -// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. The current -// version is 1. +// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. The current version +// is 1. message Question { // The proto version defining the internal structure of this question proto message. QuestionProtoVersion proto_version = 1; diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index c13b046..88b95d8 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,8 +9,7 @@ import "proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single revision card that can be displayed for a specific -// subtopic. +// Proto message representing a single revision card that can be displayed for a specific subtopic. // NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current // version is 1. message RevisionCard { @@ -35,15 +34,13 @@ message RevisionCard { // The thumbnail image for this revision card. Thumbnail thumbnail = 7; - // The list of all images that are included within SubtitledHtml subfields of this - // revision card. + // The list of all images that are included within SubtitledHtml subfields of this revision card. ReferencedImageList referenced_image_list = 8; } -// Proto message representing a subtopic ID. -// This proto message type is shared among multiple parent protos, so it has no direct -// migration pathway. Changes should be carefully done, or the proto should be duplicated -// according to whichever proto requires alterations. +// Proto message representing a subtopic ID. This proto message type is shared among multiple parent +// protos, so it has no direct migration pathway. Changes should be carefully done, or the proto +// should be duplicated according to whichever proto requires alterations. message SubtopicId { // The ID of the topic that contains this subtopic. string topic_id = 1; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 8f0c7e7..18f150c 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -10,8 +10,8 @@ option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single State. -// NOTE: Update StateProtoVersion if the structure of this proto is modified. The current -// version is 1. +// NOTE: Update StateProtoVersion if the structure of this proto is modified. The current version is +// 1. message State { StateProtoVersion proto_version = 1; @@ -66,29 +66,27 @@ message InteractionInstance { } } -// Answer type: none (N/A since no answers are submitted for this interaction). -// Structure of the continue instance. +// Answer type: none (N/A since no answers are submitted for this interaction). Structure of the +// continue instance. message ContinueInstance { CustomizationArgs customization_args = 1; // The default outcome of the continue instance. Outcome default_outcome = 2; - // Continue interactions cannot have custom answer groups, and do not support - // solutions. Users cannot receive hints since only one answer is possible - // (clicking the button). + // Continue interactions cannot have custom answer groups, and do not support solutions. Users + // cannot receive hints since only one answer is possible (clicking the button). // Structure of the customization args of continue instance. message CustomizationArgs { - // Note that while the continue interaction has a default button text - // defined, it's not used in the app since the default string needs to come - // through the app's strings so that it can be translated. + // Note that while the continue interaction has a default button text defined, it's not used in + // the app since the default string needs to come through the app's strings so that it can be + // translated. SubtitledHtml button_text = 1; } } -// Answer type: Fraction. -// Structure of the fraction input interaction. +// Answer type: Fraction. Structure of the fraction input interaction. message FractionInputInstance { // A set of arguments to customize the fraction input. @@ -231,8 +229,7 @@ message FractionInputInstance { } } -// Answer type: SetOfTranslatableHtmlContentIds. -// Structure of the item selection input interaction. +// Answer type: SetOfTranslatableHtmlContentIds. Structure of the item selection input interaction. message ItemSelectionInputInstance { // A set of arguments to customize the item selection input. @@ -313,8 +310,7 @@ message ItemSelectionInputInstance { } } -// Answer type: non-negative int (uint32). -// Structure of the multiple choice input interaction. +// Answer type: non-negative int (uint32). Structure of the multiple choice input interaction. message MultipleChoiceInputInstance { // A set of arguments to customize the multiple choice input. @@ -365,8 +361,7 @@ message MultipleChoiceInputInstance { } } -// Answer type: real (double). -// Structure of the number input interaction. +// Answer type: real (double). Structure of the number input interaction. message NumericInputInstance { // A list of answer groups of the numeric input. @@ -474,8 +469,7 @@ message NumericInputInstance { } } -// Answer type: normalized string (string). -// Structure of the text input interaction. +// Answer type: normalized string (string). Structure of the text input interaction. message TextInputInstance { // A set of arguments to customize the text input instance. @@ -564,8 +558,8 @@ message TextInputInstance { } } -// Answer type: ListOfSetsOfTranslatableHtmlContentIds. -// Structure of the drag and drop sort input interaction. +// Answer type: ListOfSetsOfTranslatableHtmlContentIds. Structure of the drag and drop sort input +// interaction. message DragAndDropSortInputInstance { // A set of arguments to customize the drag and drop sort instance. @@ -664,8 +658,7 @@ message DragAndDropSortInputInstance { } } -// Answer type: ClickOnImage. -// Structure of the image selection input interaction. +// Answer type: ClickOnImage. Structure of the image selection input interaction. message ImageClickInputInstance { // A set of arguments to customize the image click input. @@ -716,8 +709,7 @@ message ImageClickInputInstance { } } -// Answer type: RatioExpression. -// Structure of the ratio input interaction. +// Answer type: RatioExpression. Structure of the ratio input interaction. message RatioExpressionInputInstance { // A set of arguments to customize the ratio expression input. @@ -798,14 +790,13 @@ message RatioExpressionInputInstance { } } -// Answer type: none (N/A since no answers are submitted for this interaction). -// Structure of a single end exploration type interaction. +// Answer type: none (N/A since no answers are submitted for this interaction). Structure of a +// single end exploration type interaction. message EndExplorationInstance { - // No answers can be submitted to the end exploration, so there are neither - // answer groups nor solutions. The interaction does have customization - // arguments, but they aren't supported in the Android app. No default outcome - // is possible since the user takes no interactions. No hints can be shown to - // the user. + // No answers can be submitted to the end exploration, so there are neither answer groups nor + // solutions. The interaction does have customization arguments, but they aren't supported in the + // Android app. No default outcome is possible since the user takes no interactions. No hints can + // be shown to the user. } // Common fields for all answer groups. @@ -868,9 +859,10 @@ message Solution { } } -// Structure for a single misconception, after parsing the original string received from the backend: -// https://github.com/oppia/oppia/blob/896466ae8bdd34641ea2e0031a5b9fa4243a3de7/core/templates/pages/ -// exploration-editor-page/editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 +// Structure for a single misconception, after parsing the original string received from the +// backend: +// https://github.com/oppia/oppia/blob/896466ae8b/core/templates/pages/exploration-editor-page/ +// editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 message Misconception { // The id of the skill. diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index 83a9004..bde8a32 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -23,9 +23,8 @@ message TopicSummary { // The description of the topic. string description = 4; - // The size of the topic summary data is represented using one of the - // download types ("download" for a fresh download, "update" for an update to - // an existing download). + // The size of the topic summary data is represented using one of the download types ("download" + // for a fresh download, "update" for an update to an existing download). oneof download_type { // The size of the topic summary download, in bytes. diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto index 704ca99..cb60109 100644 --- a/proto/v1/structure/versions.proto +++ b/proto/v1/structure/versions.proto @@ -5,43 +5,43 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// The version of the TopicSummary proto. +// The version of the TopicSummary proto. message TopicSummaryProtoVersion { int32 version = 1; } -// The version of the RevisionCard proto. +// The version of the RevisionCard proto. message RevisionCardProtoVersion { int32 version = 1; } -// The version of the ConceptCard proto. +// The version of the ConceptCard proto. message ConceptCardProtoVersion { int32 version = 1; } -// The version of the Exploration proto. +// The version of the Exploration proto. message ExplorationProtoVersion { int32 version = 1; } -// The version of the Question proto. +// The version of the Question proto. message QuestionProtoVersion { int32 version = 1; } -// This version implies interaction compatibility since interactions are tightly defined -// in the structures. The version of the State proto. +// This version implies interaction compatibility since interactions are tightly defined in the +// structures. The version of the State proto. message StateProtoVersion { int32 version = 1; } -// The version of the Language proto. +// The version of the Language proto. message LanguageProtosVersion { int32 version = 1; } -// The version of the Image proto. +// The version of the Image proto. message ImageProtoVersion { int32 version = 1; } From ee5b1171250d636805f6ca773cf44737d3e5ae30 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 13 Oct 2021 14:36:33 -0700 Subject: [PATCH 24/51] Modularize WORKSPACE. --- WORKSPACE | 57 +++------------------------------- repo/BUILD | 3 ++ repo/deps.bzl | 75 +++++++++++++++++++++++++++++++++++++++++++++ repo/toolchains.bzl | 16 ++++++++++ 4 files changed, 98 insertions(+), 53 deletions(-) create mode 100644 repo/BUILD create mode 100644 repo/deps.bzl create mode 100644 repo/toolchains.bzl diff --git a/WORKSPACE b/WORKSPACE index 0b4760f..651582c 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -2,59 +2,10 @@ This file lists and imports all external dependencies needed to build Oppia Proto API. """ -load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") +load("//repo:deps.bzl", "initializeDepsForWorkspace") -# Set up Python (as a prerequisite dependency for Protobuf). +initializeDepsForWorkspace() -PYTHON_SHA256_HASH = "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b" -PYTHON_VERSION = "0.3.0" +load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") -http_archive( - name = "rules_python", - url = "https://github.com/bazelbuild/rules_python/releases/download/{0}/rules_python-{0}.tar.gz".format(PYTHON_VERSION), - sha256 = PYTHON_SHA256_HASH, -) - -# Set up proto & its toolchain. - -PROTOBUF_SHA256_HASH = "c6003e1d2e7fefa78a3039f19f383b4f3a61e81be8c19356f85b6461998ad3db" -PROTOBUF_VERSION = "3.17.3" - -http_archive( - name = "com_google_protobuf", - sha256 = PROTOBUF_SHA256_HASH, - strip_prefix = "protobuf-%s" % PROTOBUF_VERSION, - urls = ["https://github.com/protocolbuffers/protobuf/archive/v%s.tar.gz" % PROTOBUF_VERSION] -) - -# Set up rules_proto to allow defining proto libraries. - -# Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a -# specific commit hash. -RULES_PROTO_VERSION = "97d8af4dc474595af3900dd85cb3a29ad28cc313" -RULES_PROTO_SHA256_HASH = "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208" - -http_archive( - name = "rules_proto", - sha256 = RULES_PROTO_SHA256_HASH, - strip_prefix = "rules_proto-%s" % RULES_PROTO_VERSION, - urls = ["https://github.com/bazelbuild/rules_proto/archive/%s.tar.gz" % RULES_PROTO_VERSION], -) - -load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") -rules_proto_dependencies() -rules_proto_toolchains() - -# Set up rules_java to enable the Java proto & Java proto lite rules. -RULES_JAVA_VERSION = "0.1.1" -RULES_JAVA_SHA256_HASH = "220b87d8cfabd22d1c6d8e3cdb4249abd4c93dcc152e0667db061fb1b957ee68" - -http_archive( - name = "rules_java", - sha256 = RULES_JAVA_SHA256_HASH, - url = "https://github.com/bazelbuild/rules_java/releases/download/{0}/rules_java-{0}.tar.gz".format(RULES_JAVA_VERSION), -) - -load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") -rules_java_dependencies() -rules_java_toolchains() +initializeToolchainsForWorkspace() diff --git a/repo/BUILD b/repo/BUILD new file mode 100644 index 0000000..d0f4e48 --- /dev/null +++ b/repo/BUILD @@ -0,0 +1,3 @@ +""" +TODO: fill in +""" diff --git a/repo/deps.bzl b/repo/deps.bzl new file mode 100644 index 0000000..95ca680 --- /dev/null +++ b/repo/deps.bzl @@ -0,0 +1,75 @@ +""" +TODO: document +""" +load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") + +# Note to developers: Please keep this dict sorted by key to make it easier to find dependencies. +_DEPENDENCY_VERSIONS = { + "rules_python": { + "sha": "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b", + "url": "https://github.com/bazelbuild/rules_python/releases/download/{0}/rules_python-{0}.tar.gz", + "version": "0.3.0", + }, + "com_google_protobuf": { + "sha": "c6003e1d2e7fefa78a3039f19f383b4f3a61e81be8c19356f85b6461998ad3db", + "strip_prefix": "protobuf-{0}", + "url": "https://github.com/protocolbuffers/protobuf/archive/v{0}.tar.gz", + "version": "3.17.3", + }, + "rules_proto": { + # Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a + # specific commit hash. + "sha": "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208", + "strip_prefix": "rules_proto-{0}", + "url": "https://github.com/bazelbuild/rules_proto/archive/{0}.tar.gz", + "version": "97d8af4dc474595af3900dd85cb3a29ad28cc313", + }, + "rules_java": { + "sha": "220b87d8cfabd22d1c6d8e3cdb4249abd4c93dcc152e0667db061fb1b957ee68", + "url": "https://github.com/bazelbuild/rules_java/releases/download/{0}/rules_java-{0}.tar.gz", + "version": "0.1.1", + }, +} + +def _setUpHttpArchiveDependency(name): + metadata = _DEPENDENCY_VERSIONS[name] + sha = metadata["sha"] + strip_prefix = metadata.get("strip_prefix") + url = metadata["url"] + version = metadata["version"] + + formatted_strip_prefix = strip_prefix.format(version) if not (strip_prefix == None) else None + + http_archive( + name = name, + urls = [url.format(version)], + sha256 = sha, + strip_prefix = formatted_strip_prefix, + ) + +def _setUpPython(): + _setUpHttpArchiveDependency(name = "rules_python") + +def _setUpProtobuf(): + _setUpHttpArchiveDependency(name = "com_google_protobuf") + +def _setUpRulesProto(): + _setUpHttpArchiveDependency(name = "rules_proto") + +def _setUpRulesJava(): + _setUpHttpArchiveDependency(name = "rules_java") + +def initializeDepsForWorkspace(): + # TODO: docstring. Explain toolchain initializations that must be called may need to be called. + + # Set up Python (as a prerequisite dependency for Protobuf). + _setUpPython() + + # Set up proto & its toolchain. + _setUpProtobuf() + + # Set up rules_proto to allow defining proto libraries. + _setUpRulesProto() + + # Set up rules_java to enable the Java proto & Java proto lite rules. + _setUpRulesJava() diff --git a/repo/toolchains.bzl b/repo/toolchains.bzl new file mode 100644 index 0000000..aeebd2d --- /dev/null +++ b/repo/toolchains.bzl @@ -0,0 +1,16 @@ +""" +TODO: document +""" + +load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") +load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") + +def initializeToolchainsForWorkspace(): + # TODO: docstring explaining the load()s that need to happen before this. Explain that this file also can't be loaded until after deps are set up. + # Set up the toolchains for rules_proto. + rules_proto_dependencies() + rules_proto_toolchains() + + # Set up the toolchains for rules_java. + rules_java_dependencies() + rules_java_toolchains() From b10a3a45d0154a2ccc222685bda4d4d21d4fee7c Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 13 Oct 2021 23:20:59 -0700 Subject: [PATCH 25/51] Make protos shareable. Ensure protos have a file prefix that matches their packages. Add new rule to ratio input rule spec. Have only two java/lite library generation targets. Have one top-level shared proto lib as part of the API (for other proto libraries that depend on them). --- BUILD | 29 +++++++++++++++++--------- proto/v1/api/BUILD | 20 +++++------------- proto/v1/api/android.proto | 12 +++++------ proto/v1/structure/BUILD | 22 +++++++------------ proto/v1/structure/concept_card.proto | 6 +++--- proto/v1/structure/exploration.proto | 6 +++--- proto/v1/structure/image.proto | 2 +- proto/v1/structure/languages.proto | 14 ++++++------- proto/v1/structure/question.proto | 6 +++--- proto/v1/structure/revision_card.proto | 6 +++--- proto/v1/structure/state.proto | 25 +++++++++++++++------- proto/v1/structure/topic_summary.proto | 4 ++-- 12 files changed, 76 insertions(+), 76 deletions(-) diff --git a/BUILD b/BUILD index defc796..e377246 100644 --- a/BUILD +++ b/BUILD @@ -2,6 +2,9 @@ TODO: fill in """ +load("@rules_proto//proto:defs.bzl", "proto_library") +load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") + package_group( name = "api_visibility", packages = [ @@ -16,20 +19,26 @@ package_group( ], ) -java_library( - name = "android_java_protos", +# Note that 'deps' specifically needs to be used (versus just 'exports') since downstream +# proto_library targets otherwise won't pull in the protos, and language libraries need it to +# actually generate corresponding proto code. +proto_library( + name = "android_protos", visibility = ["//visibility:public"], - exports = [ - "//proto/v1/api:android_java_proto", - "//proto/v1/structure:structure_java_proto", + deps = [ + "//proto/v1/api:android_proto", + "//proto/v1/structure:structure_proto", ], ) -java_library( +java_proto_library( + name = "android_java_protos", + visibility = ["//visibility:public"], + deps = [":android_protos"], +) + +java_lite_proto_library( name = "android_java_lite_protos", visibility = ["//visibility:public"], - exports = [ - "//proto/v1/api:android_java_proto_lite", - "//proto/v1/structure:structure_java_proto_lite", - ], + deps = [":android_protos"], ) diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD index c0061b9..cdbed08 100644 --- a/proto/v1/api/BUILD +++ b/proto/v1/api/BUILD @@ -1,30 +1,20 @@ """ This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. -The proto_library() rule creates a proto file library for the android API -proto file to be used in multiple languages. +The proto_library() rule creates a proto file library for the android API +proto file to be used in multiple languages. The java_lite_proto_library() rule takes in a proto_library target and generates Java code. The java_proto_library() rule takes in a proto_library target and generates Java code. """ -load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") load("@rules_proto//proto:defs.bzl", "proto_library") proto_library( name = "android_proto", srcs = ["android.proto"], + visibility = ["//:api_visibility"], + strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. + import_prefix = "org/oppia/proto/v1/api", # Make directory prefix match declared package. deps = [ "//proto/v1/structure:structure_proto" ], ) - -java_proto_library( - name = "android_java_proto", - visibility = ["//:api_visibility"], - deps = [":android_proto"], -) - -java_lite_proto_library( - name = "android_java_proto_lite", - visibility = ["//:api_visibility"], - deps = [":android_proto"], -) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 5f24417..15ec3c1 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -2,12 +2,12 @@ syntax = "proto3"; package org.oppia.proto.v1.api; -import "proto/v1/structure/concept_card.proto"; -import "proto/v1/structure/exploration.proto"; -import "proto/v1/structure/question.proto"; -import "proto/v1/structure/revision_card.proto"; -import "proto/v1/structure/topic_summary.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/concept_card.proto"; +import "org/oppia/proto/v1/structure/exploration.proto"; +import "org/oppia/proto/v1/structure/question.proto"; +import "org/oppia/proto/v1/structure/revision_card.proto"; +import "org/oppia/proto/v1/structure/topic_summary.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; diff --git a/proto/v1/structure/BUILD b/proto/v1/structure/BUILD index be4d187..bc6f14d 100644 --- a/proto/v1/structure/BUILD +++ b/proto/v1/structure/BUILD @@ -1,11 +1,10 @@ """ This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. -The proto_library() rule creates a proto file library for the core proto files to be used in multiple languages. +The proto_library() rule creates a proto file library for the core proto files to be used in multiple languages. The java_lite_proto_library() rule takes in a proto_library target and generates Java code. The java_proto_library() rule takes in a proto_library target and generate Java code. """ -load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") load("@rules_proto//proto:defs.bzl", "proto_library") proto_library( @@ -22,17 +21,10 @@ proto_library( "topic_summary.proto", "versions.proto", ], - visibility = ["//:proto_impl_visibility"], -) - -java_proto_library( - name = "structure_java_proto", - visibility = ["//:api_visibility"], - deps = [":structure_proto"], -) - -java_lite_proto_library( - name = "structure_java_proto_lite", - visibility = ["//:api_visibility"], - deps = [":structure_proto"], + strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. + import_prefix = "org/oppia/proto/v1/structure", # Make directory prefix match declared package. + visibility = [ + "//:api_visibility", + "//:proto_impl_visibility", + ], ) diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index c782c8a..0ffa304 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -2,9 +2,9 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/image.proto"; -import "proto/v1/structure/languages.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 0586834..32eae1c 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -2,9 +2,9 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/image.proto"; -import "proto/v1/structure/state.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/state.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 26030c3..4552dde 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 8257334..b35ab82 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -2,13 +2,13 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// A list of language codes supported by the Android app. -enum LanguageCode { +// A list of languages supported by the Android app. +enum Language { // TODO: Add docstring to explain why this is needed and when it should be used. LANGUAGE_CODE_UNSPECIFIED = 0; ENGLISH = 1; @@ -47,8 +47,8 @@ message RecordedVoiceovers { // Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a particular // language. message VoiceoverContentMapping { - // The language code that this mapping is for. - LanguageCode language_code = 1; + // The language that this mapping is for. + Language language = 1; // The mapping of content IDs to their corresponding voiceover files. map voiceover_content_mapping = 2; @@ -80,8 +80,8 @@ message WrittenTranslations { // Proto message mapping SubtitledHtml fields to their corresponding written translations in a // particular language. message WrittenTranslationContentMapping { - // The language code that this mapping is for. - LanguageCode language_code = 1; + // The language that this mapping is for. + Language language = 1; // The mapping of content IDs to their corresponding written translations. map translation_content_mapping = 2; diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index e165880..9f3ba41 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -2,9 +2,9 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/image.proto"; -import "proto/v1/structure/state.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/state.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 88b95d8..f5cf151 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -2,9 +2,9 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/image.proto"; -import "proto/v1/structure/languages.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 18f150c..48f653d 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -2,9 +2,9 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/languages.proto"; -import "proto/v1/structure/objects.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; +import "org/oppia/proto/v1/structure/objects.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; @@ -771,6 +771,9 @@ message RatioExpressionInputInstance { // A rule to check the number of terms. HasNumberOfTermsEqualToSpec has_number_of_terms_equal_to = 3; + + // A rule to check whether a ratio has a specific term with a specific value. + HasSpecificTermEqualToSpec has_specific_term_equal_to = 4; } // Structure of the equal rule check. @@ -783,20 +786,26 @@ message RatioExpressionInputInstance { RatioExpression input = 1; } - // Structure of the numer of terms equal rule check. + // Structure of the number of terms equal rule check. message HasNumberOfTermsEqualToSpec { uint32 input_term_count = 1; } + + // Structure of the specific terms rule check. + message HasSpecificTermEqualToSpec { + uint32 input_term_index = 1; + uint32 input_expected_term_value = 2; + } } } // Answer type: none (N/A since no answers are submitted for this interaction). Structure of a // single end exploration type interaction. message EndExplorationInstance { - // No answers can be submitted to the end exploration, so there are neither answer groups nor - // solutions. The interaction does have customization arguments, but they aren't supported in the - // Android app. No default outcome is possible since the user takes no interactions. No hints can - // be shown to the user. + // No answers can be submitted to the end exploration interaction, so there are neither answer + // groups nor solutions. The interaction does have customization arguments, but they aren't + // supported in the Android app. No default outcome is possible since the user takes no + // interactions. No hints can be shown to the user. } // Common fields for all answer groups. diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index bde8a32..b012114 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -2,8 +2,8 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "proto/v1/structure/image.proto"; -import "proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; From 9afead938694c308f6adbb1e4f244f67347a0ca0 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 14 Oct 2021 13:15:10 -0700 Subject: [PATCH 26/51] Revise topic list API. This makes the topic list API resilient to structural changes causing inconsistencies in the displayed topic list, provides more robustness to potential server mistakes (by letting the client partially recover), and provides the basic support necessary for incremental updates without necessarily mandating them in the initial implementation. --- proto/v1/api/android.proto | 135 +++++++++++++++++++------ proto/v1/structure/topic_summary.proto | 21 +--- 2 files changed, 111 insertions(+), 45 deletions(-) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 15ec3c1..08d9837 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -22,7 +22,7 @@ message TopicListRequest { // Details about the latest proto versions that this Android client can support. ClientCompatibilityContext compatibility_context = 3; // TODO: Fill this in. - ClientDownloadStateContext download_context = 4; + repeated VersionedStructureMetadata current_downloads_context = 4; } // The expected proto response from the server when provided with a TopicListRequest. @@ -30,9 +30,84 @@ message TopicListResponse { // The common proto version defining this request/response pair. TopicListRequestResponseProtoVersion proto_version = 1; - // A list of the latest topic summaries that are newer than the ones stored on the client, but - // still compatible with the client. - repeated org.oppia.proto.v1.structure.TopicSummary topic_summaries = 2; + // A list of all topics that are compatibly available to the client whose context corresponds to + // this response. Note that topics marked as available for downloading or updating will always be + // compatible with the local client, and topics that are marked as up-to-date are guaranteed to + // be at the latest compatible version for the local client. Clients are also expected to lean on + // existing local resources for topics that aren't yet downloaded. + repeated AvailableTopic available_topics = 2; + + // A topic that's available to & compatible with the local client. + message AvailableTopic { + // The nature of the topic's availability. + oneof availability_type { + // Indicates a topic that's not yet downloaded by the local client, but is available to be + // downloaded. + DownloadableTopic downloadable_topic = 1; + + // Indicates a topic that's downloaded by the local client, but has a compatible update. + UpdatableTopic updatable_topic = 2; + + // Indicates a topic that's both downloaded by the local client & full up-to-date. This mainly + // serves as a lightweight indicator to ensure that the server & client are properly in-sync + // with the state of the local client. + UpToDateTopic up_to_date_topic = 3; + } + } + + // Represents a topic that's available to download and is not yet downloaded by the local client. + message DownloadableTopic { + // The ID of the topic that's available to newly download. This is expected to be used to + // identify the local copy of the topic's summary in the event that the topic_summary field is + // empty. Note that content_version is not also included since topic_summary is only missing if + // the local client already has the latest, most up-to-date summary (including the corresponding + // content version). + string topic_id = 1; + + // The full summary for the current topic. Note that this will be absent if the local client + // already has the latest summary downloaded as indicated by its download state context. + org.oppia.proto.v1.structure.TopicSummary topic_summary = 2; + + // The size, in bytes, needed to download the topic. + uint32 download_size_bytes = 3; + } + + // Represents a topic that's available to be updated. Clients should use their existing topic + // summary when displaying this topic, and not update it until the user requests to download the + // topic. Future iterations of this API could include a preview summary here for clients to + // provide context on the changes to the topic to help inform users. + message UpdatableTopic { + // The ID of the topic that's available to be updated. This is expected to correspond to an + // existing summary that the local client already has for the topic. In the event it doesn't, it + // may use the topic content API to retrieve the topic summary & treat this as a topic that's + // available to download. + string topic_id = 1; + + // The new topic content version that may be updated to (as compared with the local summary for + // this topic which should have a smaller content version). + uint32 content_version = 2; + + // The size, in bytes, required to download all missing pieces to update this topic. + uint32 update_size_bytes = 3; + + // The precise list of structures that need to be updated in the local client in order to update + // the topic. This may be a full update of the topic, but the server may also attempt to perform + // an incremental update to minimize the download work & bandwidth needed by the local client. + // update_size_bytes will reflect the data determined by the server to be needed to update the + // topic. + repeated VersionedStructureMetadata updated_structures = 4; + } + + // Represents a topic that's been downloaded by the local client and is fully up-to-date. + message UpToDateTopic { + // The ID of the topic that the server believes the local client has downloaded. In the event + // that this is incorrect, this topic can be treated as downloadable & its summary can be + // fetched using the topic cnotent API. + string topic_id = 1; + + // The content version of the topic that the server believes the local client has downloaded. + uint32 content_version = 2; + } } // The proto request made to the server to get the latest still-compatible content for specific @@ -73,11 +148,12 @@ message TopicContentResponse { // of this value in the oneof is sufficient to indicate its state; its actual value does not // matter. bool skipped = 2; - org.oppia.proto.v1.structure.RevisionCard revision_card = 3; - org.oppia.proto.v1.structure.ConceptCard concept_card = 4; - org.oppia.proto.v1.structure.Exploration exploration = 5; - QuestionIdList question_id_list = 6; - org.oppia.proto.v1.structure.Question question = 7; + org.oppia.proto.v1.structure.TopicSummary topic_summary = 3; + org.oppia.proto.v1.structure.RevisionCard revision_card = 4; + org.oppia.proto.v1.structure.ConceptCard concept_card = 5; + org.oppia.proto.v1.structure.Exploration exploration = 6; + QuestionIdList question_id_list = 7; + org.oppia.proto.v1.structure.Question question = 8; } } @@ -121,39 +197,40 @@ message ClientCompatibilityContext { org.oppia.proto.v1.structure.ImageProtoVersion thumbnail_proto_version = 8; } -// TODO: Document this fully. -message ClientDownloadStateContext { - message DownloadState { - int32 content_version = 1; - oneof structure_type { - string topic_id = 2; - org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; - string concept_card_id = 4; - string story_id = 5; - string exploration_id = 6; - string question_id = 7; - string skill_id = 8; - } +// TODO: Document this fully. TopicListRequestResponseProtoVersion must be updated for structural +// changes to this message. +message VersionedStructureMetadata { + int32 content_version = 1; + oneof structure_type { + string topic_id = 2; + string topic_summary_id = 3; + org.oppia.proto.v1.structure.SubtopicId revision_card_id = 4; + string concept_card_id = 5; + string story_id = 6; + string exploration_id = 7; + string question_id = 8; + string skill_id = 9; } - - repeated DownloadState current_downloads = 1; } // The type and ID of a specific asset that is being downloaded. // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is modified. message DownloadRequestStructureIdentifier { + uint32 content_version = 1; + oneof structure_type { + string topic_summary_id = 2; // The ID of the revision card ("subtopic") to be downloaded. - org.oppia.proto.v1.structure.SubtopicId revision_card_id = 1; + org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; // The ID of the concept card to be downloaded. - string concept_card_id = 2; + string concept_card_id = 4; // The ID of the exploration to be downloaded. - string exploration_id = 3; + string exploration_id = 5; // The skill ID whose associated questions are to be downloaded. // TODO: Clarify difference between this and concept_card_id above (field 2). - string question_list_skill_id = 4; + string question_list_skill_id = 6; // The ID of the question to be downloaded. - string question_id = 5; + string question_id = 7; } } diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index b012114..e4e196b 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -23,31 +23,20 @@ message TopicSummary { // The description of the topic. string description = 4; - // The size of the topic summary data is represented using one of the download types ("download" - // for a fresh download, "update" for an update to an existing download). - oneof download_type { - - // The size of the topic summary download, in bytes. - int32 download_size_bytes = 5; - - // The size of the topic summary update, in bytes. - int32 update_size_bytes = 6; - } - // A list of story summaries related to this TopicSummary. - repeated StorySummary story_summaries = 7; + repeated StorySummary story_summaries = 5; // A list of all the subtopic indexes contained in this topic. - repeated int32 subtopic_indexes = 8; + repeated int32 subtopic_indexes = 6; // The thumbnail image corresponding to this topic. - Thumbnail thumbnail = 9; // TODO + Thumbnail thumbnail = 7; // TODO // Whether the corresponding topic has been published. - bool is_published = 10; + bool is_published = 8; // The version of this topic's contents. - int32 content_version = 11; + int32 content_version = 9; } // Structure of a single story summary. From 97a134d1162ef6159c1939ad219436ccc5b278e2 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 14 Oct 2021 14:17:33 -0700 Subject: [PATCH 27/51] Annotate protos with their version types. This is a much clearer way to denote which structure versions correspond to which proto, and actually allows us to potentially enforce it API-wide. --- BUILD | 1 + proto/v1/api/BUILD | 3 +- proto/v1/api/android.proto | 77 ++++++++----- proto/v1/structure/BUILD | 4 +- proto/v1/structure/concept_card.proto | 9 +- proto/v1/structure/exploration.proto | 8 +- proto/v1/structure/image.proto | 14 +-- proto/v1/structure/languages.proto | 31 ++++- proto/v1/structure/objects.proto | 4 +- proto/v1/structure/question.proto | 8 +- proto/v1/structure/revision_card.proto | 15 ++- proto/v1/structure/state.proto | 125 ++++++++++++++++++++- proto/v1/structure/topic_summary.proto | 16 ++- proto/v1/structure/versions.proto | 47 -------- proto/v1/versions/BUILD.bazel | 22 ++++ proto/v1/versions/api_versions.proto | 37 ++++++ proto/v1/versions/structure_versions.proto | 86 ++++++++++++++ 17 files changed, 386 insertions(+), 121 deletions(-) delete mode 100644 proto/v1/structure/versions.proto create mode 100644 proto/v1/versions/BUILD.bazel create mode 100644 proto/v1/versions/api_versions.proto create mode 100644 proto/v1/versions/structure_versions.proto diff --git a/BUILD b/BUILD index e377246..38de2a3 100644 --- a/BUILD +++ b/BUILD @@ -28,6 +28,7 @@ proto_library( deps = [ "//proto/v1/api:android_proto", "//proto/v1/structure:structure_proto", + "//proto/v1/versions:versions_proto", ], ) diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD index cdbed08..b102549 100644 --- a/proto/v1/api/BUILD +++ b/proto/v1/api/BUILD @@ -15,6 +15,7 @@ proto_library( strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. import_prefix = "org/oppia/proto/v1/api", # Make directory prefix match declared package. deps = [ - "//proto/v1/structure:structure_proto" + "//proto/v1/structure:structure_proto", + "//proto/v1/versions:versions_proto", ], ) diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 08d9837..30fb53e 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -7,15 +7,18 @@ import "org/oppia/proto/v1/structure/exploration.proto"; import "org/oppia/proto/v1/structure/question.proto"; import "org/oppia/proto/v1/structure/revision_card.proto"; import "org/oppia/proto/v1/structure/topic_summary.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/api_versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; // The proto request made to the server to get the list of topics which are available for download. message TopicListRequest { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The common proto version defining this request/response pair. - TopicListRequestResponseProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion proto_version = 1; // Details about the Android app client that is making the request. ClientContext client_context = 2; @@ -27,8 +30,10 @@ message TopicListRequest { // The expected proto response from the server when provided with a TopicListRequest. message TopicListResponse { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The common proto version defining this request/response pair. - TopicListRequestResponseProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion proto_version = 1; // A list of all topics that are compatibly available to the client whose context corresponds to // this response. Note that topics marked as available for downloading or updating will always be @@ -39,6 +44,8 @@ message TopicListResponse { // A topic that's available to & compatible with the local client. message AvailableTopic { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The nature of the topic's availability. oneof availability_type { // Indicates a topic that's not yet downloaded by the local client, but is available to be @@ -57,6 +64,8 @@ message TopicListResponse { // Represents a topic that's available to download and is not yet downloaded by the local client. message DownloadableTopic { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The ID of the topic that's available to newly download. This is expected to be used to // identify the local copy of the topic's summary in the event that the topic_summary field is // empty. Note that content_version is not also included since topic_summary is only missing if @@ -77,6 +86,8 @@ message TopicListResponse { // topic. Future iterations of this API could include a preview summary here for clients to // provide context on the changes to the topic to help inform users. message UpdatableTopic { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The ID of the topic that's available to be updated. This is expected to correspond to an // existing summary that the local client already has for the topic. In the event it doesn't, it // may use the topic content API to retrieve the topic summary & treat this as a topic that's @@ -100,6 +111,8 @@ message TopicListResponse { // Represents a topic that's been downloaded by the local client and is fully up-to-date. message UpToDateTopic { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The ID of the topic that the server believes the local client has downloaded. In the event // that this is incorrect, this topic can be treated as downloadable & its summary can be // fetched using the topic cnotent API. @@ -113,8 +126,10 @@ message TopicListResponse { // The proto request made to the server to get the latest still-compatible content for specific // topics. message TopicContentRequest { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + // The common proto version defining this request/response pair. - TopicContentRequestResponseProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion proto_version = 1; // Details about the Android app client that is making the request. ClientContext client_context = 2; @@ -128,17 +143,19 @@ message TopicContentRequest { // The expected proto response from the server when provided with a TopicContentRequest. message TopicContentResponse { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + // The common proto version defining this request/response pair. - TopicContentRequestResponseProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion proto_version = 1; // A list of the individual items to be downloaded. repeated DownloadResult download_results = 2; // The result of downloading a specific asset. This may either contain the result of the download, // or an indication that the download was skipped. - // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is - // modified. The current version is 1. message DownloadResult { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + // The entity type and ID corresponding to this download. DownloadRequestStructureIdentifier identifier = 1; @@ -158,9 +175,9 @@ message TopicContentResponse { } // A list of question IDs corresponding to the topic. - // NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is - // modified. The current version is 1. message QuestionIdList { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + // The list of question IDs. repeated string question_ids = 1; } @@ -168,6 +185,8 @@ message TopicContentResponse { // TODO: Add docs. message ClientContext { + option (org.oppia.proto.v1.versions.api_proto_version_type) = UNVERSIONED_API_PROTO; + // TODO: Add doc and clarify name. string version_name = 1; // TODO: Add doc and clarify name. @@ -177,29 +196,34 @@ message ClientContext { // Information about the latest proto versions that the client can support. // TODO: Clarify whether, if a client can support version N, this means it can support // versions 1 to N, or only version N. If neither of these, then we might need a -// "from ... to" range for each field, rather than a single version. +// "from ... to" range for each field, rather than a single version. Note for future documentation +// iteration: clients only guarantee exact support. Onus is on the server to supply the exact proto +// structure version for client compatibility (which should always be possible per design of proto). message ClientCompatibilityContext { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The latest proto version for topic summaries that the client can support. - org.oppia.proto.v1.structure.TopicSummaryProtoVersion topic_summary_proto_version = 1; + org.oppia.proto.v1.versions.TopicSummaryProtoVersion topic_summary_proto_version = 1; // The latest proto version for revision cards that the client can support. - org.oppia.proto.v1.structure.RevisionCardProtoVersion revision_card_proto_version = 2; + org.oppia.proto.v1.versions.RevisionCardProtoVersion revision_card_proto_version = 2; // The latest proto version for concept cards that the client can support. - org.oppia.proto.v1.structure.ConceptCardProtoVersion concept_card_proto_version = 3; + org.oppia.proto.v1.versions.ConceptCardProtoVersion concept_card_proto_version = 3; // The latest proto version for explorations that the client can support. - org.oppia.proto.v1.structure.ExplorationProtoVersion exploration_proto_version = 4; + org.oppia.proto.v1.versions.ExplorationProtoVersion exploration_proto_version = 4; // The latest proto version for questions that the client can support. - org.oppia.proto.v1.structure.QuestionProtoVersion question_proto_version = 5; + org.oppia.proto.v1.versions.QuestionProtoVersion question_proto_version = 5; // The latest proto version for states that the client can support. - org.oppia.proto.v1.structure.StateProtoVersion state_proto_version = 6; + org.oppia.proto.v1.versions.StateProtoVersion state_proto_version = 6; // The latest proto version for language-related protos that the client can support. - org.oppia.proto.v1.structure.LanguageProtosVersion language_protos_version = 7; + org.oppia.proto.v1.versions.LanguageProtosVersion language_protos_version = 7; // The latest proto version for images that the client can support. - org.oppia.proto.v1.structure.ImageProtoVersion thumbnail_proto_version = 8; + org.oppia.proto.v1.versions.ImageProtoVersion thumbnail_proto_version = 8; } -// TODO: Document this fully. TopicListRequestResponseProtoVersion must be updated for structural -// changes to this message. +// TODO: Document this fully. message VersionedStructureMetadata { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + int32 content_version = 1; oneof structure_type { string topic_id = 2; @@ -214,8 +238,9 @@ message VersionedStructureMetadata { } // The type and ID of a specific asset that is being downloaded. -// NOTE: Update TopicContentRequestResponseProtoVersion if the structure of this proto is modified. message DownloadRequestStructureIdentifier { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + uint32 content_version = 1; oneof structure_type { @@ -233,13 +258,3 @@ message DownloadRequestStructureIdentifier { string question_id = 7; } } - -// The only currently-supported proto version for the TopicListRequestResponse. -message TopicListRequestResponseProtoVersion { - int32 version = 1; -} - -// The only currently-supported proto version for the TopicContentRequestResponse. -message TopicContentRequestResponseProtoVersion { - int32 version = 1; -} diff --git a/proto/v1/structure/BUILD b/proto/v1/structure/BUILD index bc6f14d..5a29aac 100644 --- a/proto/v1/structure/BUILD +++ b/proto/v1/structure/BUILD @@ -19,7 +19,6 @@ proto_library( "revision_card.proto", "state.proto", "topic_summary.proto", - "versions.proto", ], strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. import_prefix = "org/oppia/proto/v1/structure", # Make directory prefix match declared package. @@ -27,4 +26,7 @@ proto_library( "//:api_visibility", "//:proto_impl_visibility", ], + deps = [ + "//proto/v1/versions:versions_proto", + ], ) diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index 0ffa304..c73645c 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -4,17 +4,17 @@ package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/languages.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single concept card that can be displayed for a specific skill. -// NOTE: Update ConceptCardProtoVersion if the structure of this proto is modified. The current -// version is 1. message ConceptCard { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; + // The proto version defining the internal structure of this concept card proto message. - ConceptCardProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.ConceptCardProtoVersion proto_version = 1; // The ID corresponding to the skill this concept is representing. string skill_id = 2; @@ -40,6 +40,7 @@ message ConceptCard { // Each worked example provides a sample question and answer for the student to read and learn // from. message WorkedExample { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; // The question for this worked example. SubtitledHtml question = 1; diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 32eae1c..4bc6bf0 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -4,17 +4,17 @@ package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/state.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single exploration. -// NOTE: Update ExplorationProtoVersion if the structure of this proto is modified. The current -// version is 1. message Exploration { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = EXPLORATION_PROTO_VERSION; + // The proto version defining the internal structure of this exploration proto message. - ExplorationProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.ExplorationProtoVersion proto_version = 1; // The ID of the exploration. string id = 2; diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index 4552dde..dd562d8 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -2,17 +2,17 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single thumbnail image. -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current version -// is 1. message Thumbnail { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; + // The proto version defining the internal structure of this image proto message. - ImageProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; // The name of the thumbnail image file. string filename = 2; @@ -21,12 +21,12 @@ message Thumbnail { int32 background_color_rgb = 3; } -// NOTE: Update ImageProtoVersion if the structure of this proto is modified. The current version -// is 1. // Proto representing a list of images. message ReferencedImageList { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; + // The proto version defining the internal structure of this list of images. - ImageProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; // The list of filenames of all the images in the list. repeated string referenced_image_filenames = 2; diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index b35ab82..6e983a6 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; @@ -19,11 +19,12 @@ enum Language { } // Proto message representing a block of (subtitled) HTML. -// NOTE: Update LanguageProtosVersion if the structure of this proto is modified. message SubtitledHtml { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The proto version defining the internal structure of this proto message. // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. - LanguageProtosVersion protos_version = 1; + org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; // The content ID for this SubtitledHtml. This is unique within a State. string content_id = 2; @@ -33,11 +34,12 @@ message SubtitledHtml { } // Proto message representing recorded voiceovers. -// NOTE: Update LanguageProtosVersion if the structure of this proto is modified. message RecordedVoiceovers { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The proto version defining the internal structure of this proto message. // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. - LanguageProtosVersion protos_version = 1; + org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; // A list of mappings from language codes to voiceover bundles (which each map individual // SubtitledHtml content IDs to their voiceovers in that language). @@ -47,6 +49,8 @@ message RecordedVoiceovers { // Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a particular // language. message VoiceoverContentMapping { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The language that this mapping is for. Language language = 1; @@ -56,6 +60,8 @@ message VoiceoverContentMapping { // Proto message representing a specific voiceover file. message Voiceover { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The file name of the voiceover. string filename = 1; @@ -68,9 +74,11 @@ message Voiceover { // Proto message representing a set of written translations. message WrittenTranslations { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The proto version defining the internal structure of this proto message. // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. - LanguageProtosVersion protos_version = 1; + org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; // A list of mappings from language codes to written translations (which each map individual // SubtitledHtml content IDs to their written translations in that language). @@ -80,6 +88,8 @@ message WrittenTranslations { // Proto message mapping SubtitledHtml fields to their corresponding written translations in a // particular language. message WrittenTranslationContentMapping { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The language that this mapping is for. Language language = 1; @@ -89,6 +99,7 @@ message WrittenTranslationContentMapping { // Proto message representing a single written translation. message WrittenTranslation { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The data format of the source material for this translation. oneof data_format { @@ -108,11 +119,15 @@ message WrittenTranslation { // Proto message representing the translation of a single HTML string. message WrittenTranslatableHtml { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + string translation = 1; } // Proto message representing the translation of a single unicode string. message WrittenTranslatableUnicode { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + string translation = 1; } @@ -120,6 +135,8 @@ message WrittenTranslatableUnicode { // translations have a variable number of strings, the number of which may be different from the // number of strings in the original set. message WrittenTranslatableSetOfNormalizedString { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + repeated string translation = 1; } @@ -127,5 +144,7 @@ message WrittenTranslatableSetOfNormalizedString { // translations have a variable number of strings, the number of which may be different from the // number of strings in the original set. message WrittenTranslatableSetOfUnicodeString { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + repeated string translation = 1; } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index d85a959..5ded563 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -5,9 +5,11 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// TODO: split up this proto into rule-spec based objects & update the versions accordingly. +// Anything not typed to rule inputs should go into the correct file with the correct versions. + // Proto message representing a single fraction or mixed number. message Fraction { - // Whether the fraction is negative. bool is_negative = 1; diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 9f3ba41..50536f7 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -4,17 +4,17 @@ package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/state.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; // Proto message representing a single question. -// NOTE: Update QuestionProtoVersion if the structure of this proto is modified. The current version -// is 1. message Question { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = QUESTION_PROTO_VERSION; + // The proto version defining the internal structure of this question proto message. - QuestionProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.QuestionProtoVersion proto_version = 1; // The ID of the question. string id = 2; diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index f5cf151..7d64f3a 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -4,7 +4,7 @@ package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/languages.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; @@ -13,8 +13,10 @@ option java_multiple_files = true; // NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current // version is 1. message RevisionCard { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = REVISION_CARD_PROTO_VERSION; + // The proto version defining the internal structure of this revision card proto message. - RevisionCardProtoVersion proto_version = 1; + org.oppia.proto.v1.versions.RevisionCardProtoVersion proto_version = 1; // The id of the subtopic in which this revision card is displayed. SubtopicId id = 2; @@ -38,10 +40,13 @@ message RevisionCard { ReferencedImageList referenced_image_list = 8; } -// Proto message representing a subtopic ID. This proto message type is shared among multiple parent -// protos, so it has no direct migration pathway. Changes should be carefully done, or the proto -// should be duplicated according to whichever proto requires alterations. +// Proto message representing a subtopic ID. message SubtopicId { + // This proto message type is shared among multiple parent protos, so it has no direct migration + // pathway. Changes should be carefully done, or the proto should be duplicated according to + // whichever proto requires alterations. + option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + // The ID of the topic that contains this subtopic. string topic_id = 1; diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index 48f653d..eff7eb6 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -4,16 +4,18 @@ package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/structure/objects.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; +// TODO: add customization args defaults & CI check to cross-validate them with web? + // Proto message representing a single State. -// NOTE: Update StateProtoVersion if the structure of this proto is modified. The current version is -// 1. message State { - StateProtoVersion proto_version = 1; + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + org.oppia.proto.v1.versions.StateProtoVersion proto_version = 1; // The content of the state. SubtitledHtml content = 2; @@ -30,6 +32,7 @@ message State { // Structure for a single interaction. message InteractionInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The different types of interactions. oneof interaction_type { @@ -69,6 +72,8 @@ message InteractionInstance { // Answer type: none (N/A since no answers are submitted for this interaction). Structure of the // continue instance. message ContinueInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + CustomizationArgs customization_args = 1; // The default outcome of the continue instance. @@ -79,6 +84,8 @@ message ContinueInstance { // Structure of the customization args of continue instance. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Note that while the continue interaction has a default button text defined, it's not used in // the app since the default string needs to come through the app's strings so that it can be // translated. @@ -88,6 +95,7 @@ message ContinueInstance { // Answer type: Fraction. Structure of the fraction input interaction. message FractionInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the fraction input. CustomizationArgs customization_args = 1; @@ -106,6 +114,7 @@ message FractionInputInstance { // Structure of the customization args of the fraction input. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The fraction is in simplest form or not. bool requires_simplest_form = 1; @@ -122,6 +131,7 @@ message FractionInputInstance { // Structure of the solution of the fraction input. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; @@ -132,6 +142,7 @@ message FractionInputInstance { // Structure of the answer group of the fraction input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -142,6 +153,7 @@ message FractionInputInstance { // Structure of the rule spec of the fraction input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different rules which can be applied on the fraction input. oneof rule_type { @@ -179,51 +191,71 @@ message FractionInputInstance { // Structure of the exactly equal rule check. message IsExactlyEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } // Structure of the equivalent rule check. message IsEquivalentToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } // Structure of the equivalent and simple form rule check. message IsEquivalentToAndInSimplestFormSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } // Structure of the less than rule check. message IsLessThanSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } // Structure of the greater than rule check. message IsGreaterThanSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } // Structure of the numerator equality rule check. message HasNumeratorEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + int32 input = 1; } // Structure of the denominator equality rule check. message HasDenominatorEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + uint32 input = 1; } // Structure of the integer part rule check. message HasIntegerPartEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + int32 input = 1; } // Structure of the no fraction input rule check. message HasNoFractionalPartSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // No inputs for this rule spec. } // Structure of the fraction part exactly equality rule check. message HasFractionalPartExactlyEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + Fraction input = 1; } } @@ -231,6 +263,7 @@ message FractionInputInstance { // Answer type: SetOfTranslatableHtmlContentIds. Structure of the item selection input interaction. message ItemSelectionInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the item selection input. CustomizationArgs customization_args = 1; @@ -248,6 +281,7 @@ message ItemSelectionInputInstance { // Structure of the customization args of the item selection input. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The minimum number of items allowed for selection. int32 min_allowable_selection_count = 1; @@ -261,6 +295,7 @@ message ItemSelectionInputInstance { // Structure of a single answer group of item selection input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -271,6 +306,7 @@ message ItemSelectionInputInstance { // Structure of the rules of the item selection input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different type of rules for the item selection input instance. oneof rule_type { @@ -290,21 +326,29 @@ message ItemSelectionInputInstance { // Structure of the equal rule check. message EqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + SetOfTranslatableHtmlContentIds input = 1; } // Structure of atleast one item selection rule check. message ContainsAtLeastOneOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + SetOfTranslatableHtmlContentIds input = 1; } // Structure of non of the item selection rule check. message DoesNotContainAtLeastOneOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + SetOfTranslatableHtmlContentIds input = 1; } // Structure of proper subset of item selection rule check. message IsProperSubsetOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + SetOfTranslatableHtmlContentIds input = 1; } } @@ -312,6 +356,7 @@ message ItemSelectionInputInstance { // Answer type: non-negative int (uint32). Structure of the multiple choice input interaction. message MultipleChoiceInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the multiple choice input. CustomizationArgs customization_args = 1; @@ -329,6 +374,7 @@ message MultipleChoiceInputInstance { // Structure of the customization args of the multiple choice input. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A list of possible choices from the multiple items. repeated SubtitledHtml choices = 1; @@ -336,6 +382,7 @@ message MultipleChoiceInputInstance { // Structure of a single answer group of multiple choice input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A base answer group is a set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -346,6 +393,7 @@ message MultipleChoiceInputInstance { // Structure of the rules of the multiple choice input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Differnt type of rules for the multiple choice input. oneof rule_type { @@ -356,6 +404,8 @@ message MultipleChoiceInputInstance { // Structure of the equal rule check. message EqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + uint32 input = 1; } } @@ -363,6 +413,7 @@ message MultipleChoiceInputInstance { // Answer type: real (double). Structure of the number input interaction. message NumericInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A list of answer groups of the numeric input. repeated AnswerGroup answer_groups = 1; @@ -376,6 +427,7 @@ message NumericInputInstance { // Structure of the solution of the numeric input. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; @@ -386,6 +438,7 @@ message NumericInputInstance { // Structure of a single answer group of numeric input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -396,6 +449,7 @@ message NumericInputInstance { // Structure of the rules of the numeric input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different type of rules which can be applied on the numeric input. oneof rule_type { @@ -424,31 +478,42 @@ message NumericInputInstance { // Structure of the equal rule check. message EqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + double input = 1; } // Structure of the less than rule check. message IsLessThanSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + double input = 1; } // Structure of the greater than rule check. message IsGreaterThanSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + double input = 1; } // Structure of the less than or equal rule check. message IsLessThanOrEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + double input = 1; } // Structure of the greater than or equal rule check. message IsGreaterThanOrEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + double input = 1; } // Structure of the inclusive range rule check. message IsInclusivelyBetweenSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // lower value in inclusive range. double inputLowerInclusive = 1; @@ -459,6 +524,7 @@ message NumericInputInstance { // Structure of the tolerance ranage rule check. message IsWithinToleranceSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Input tolerance value. double inputTolerance = 1; @@ -471,6 +537,7 @@ message NumericInputInstance { // Answer type: normalized string (string). Structure of the text input interaction. message TextInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the text input instance. CustomizationArgs customization_args = 1; @@ -489,6 +556,7 @@ message TextInputInstance { // Structure of the customization args of the text input instance. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A placeholder value for the text input instance. SubtitledHtml placeholder = 1; @@ -499,6 +567,7 @@ message TextInputInstance { // Structure of the solution of the text input instance. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; @@ -509,6 +578,7 @@ message TextInputInstance { // Structure of a single answer group of text input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -519,6 +589,7 @@ message TextInputInstance { // Structure of the rules of the text input instance. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different rules which can be applied on the text input instance. oneof rule_type { @@ -538,21 +609,29 @@ message TextInputInstance { // Structure of the equal rule check. message EqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + TranslatableSetOfNormalizedString input = 1; } // Structure of the rule to check starting text. message StartsWithSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + TranslatableSetOfNormalizedString input = 1; } // Structureof the rule to check the substring of the text. message ContainsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + TranslatableSetOfNormalizedString input = 1; } // Structure of the rule to check text equality. message FuzzyEqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + TranslatableSetOfNormalizedString input = 1; } } @@ -561,6 +640,7 @@ message TextInputInstance { // Answer type: ListOfSetsOfTranslatableHtmlContentIds. Structure of the drag and drop sort input // interaction. message DragAndDropSortInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the drag and drop sort instance. CustomizationArgs customization_args = 1; @@ -579,6 +659,7 @@ message DragAndDropSortInputInstance { // Structure of the customization args of the drag and drop sort instance. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A list of choice for drag and drop. repeated SubtitledHtml choices = 1; @@ -589,6 +670,7 @@ message DragAndDropSortInputInstance { // Structure of the solution of the drag and drop sort instance. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; @@ -599,6 +681,7 @@ message DragAndDropSortInputInstance { // Structure of a single answer group of drag and drop sort input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -609,6 +692,7 @@ message DragAndDropSortInputInstance { // Structure of the rules of the drag and drop sort instance. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different rules which can be applied on the drag and drop sort instance. oneof rule_type { @@ -628,16 +712,21 @@ message DragAndDropSortInputInstance { // Structure of an equal order rule. message IsEqualToOrderingSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + ListOfSetsOfTranslatableHtmlContentIds input = 1; } // Structure of an equal order with one incorrect position rule. message IsEqualToOrderingWithOneItemAtIncorrectPositionSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + ListOfSetsOfTranslatableHtmlContentIds input = 1; } // Structure of an item position check rule. message HasElementXAtPositionYSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The item whose position to check. TranslatableHtmlContentId element = 1; @@ -648,6 +737,7 @@ message DragAndDropSortInputInstance { // Structure of an item previous position check rule. message HasElementXBeforeElementYSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The previous position of an item. TranslatableHtmlContentId considered_element = 1; @@ -660,6 +750,7 @@ message DragAndDropSortInputInstance { // Answer type: ClickOnImage. Structure of the image selection input interaction. message ImageClickInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the image click input. CustomizationArgs customization_args = 1; @@ -677,6 +768,7 @@ message ImageClickInputInstance { // Structure of the customization args of the image click input. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // An image with the regions. ImageWithRegions image_and_regions = 1; @@ -684,6 +776,7 @@ message ImageClickInputInstance { // Structure of a single answer group of image selection input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A base answer group is a set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -694,6 +787,7 @@ message ImageClickInputInstance { // Structure of the rules of the image click input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different rules which can be applied on the image click input. oneof rule_type { @@ -704,6 +798,8 @@ message ImageClickInputInstance { // Structure of a single is in region. message IsInRegionSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + string input_region = 1; } } @@ -711,6 +807,7 @@ message ImageClickInputInstance { // Answer type: RatioExpression. Structure of the ratio input interaction. message RatioExpressionInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of arguments to customize the ratio expression input. CustomizationArgs customization_args = 1; @@ -729,6 +826,7 @@ message RatioExpressionInputInstance { // Structure of the customization args of the ratio expression input. message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A placeholder for the ratio expression input. SubtitledHtml placeholder = 1; @@ -739,6 +837,7 @@ message RatioExpressionInputInstance { // Structure of the solution of the ratio expression input. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the solution in all interactions. BaseSolution base_solution = 1; @@ -749,6 +848,7 @@ message RatioExpressionInputInstance { // Structure of a single answer group of ratio expression input. message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // A set of common items for the answer groups in all the interactions. BaseAnswerGroup base_answer_group = 1; @@ -759,6 +859,7 @@ message RatioExpressionInputInstance { // Structure of the rules of the ratio expression input. message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Different rules which can be applied on the ratio expression input. oneof rule_type { @@ -778,21 +879,29 @@ message RatioExpressionInputInstance { // Structure of the equal rule check. message EqualsSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + RatioExpression input = 1; } // Structure of the equivalent rule check. message IsEquivalentSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + RatioExpression input = 1; } // Structure of the number of terms equal rule check. message HasNumberOfTermsEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + uint32 input_term_count = 1; } // Structure of the specific terms rule check. message HasSpecificTermEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + uint32 input_term_index = 1; uint32 input_expected_term_value = 2; } @@ -802,6 +911,8 @@ message RatioExpressionInputInstance { // Answer type: none (N/A since no answers are submitted for this interaction). Structure of a // single end exploration type interaction. message EndExplorationInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // No answers can be submitted to the end exploration interaction, so there are neither answer // groups nor solutions. The interaction does have customization arguments, but they aren't // supported in the Android app. No default outcome is possible since the user takes no @@ -810,6 +921,7 @@ message EndExplorationInstance { // Common fields for all answer groups. message BaseAnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // An outcome is a common way of reponse for all interactions. Outcome outcome = 1; @@ -820,6 +932,7 @@ message BaseAnswerGroup { // Structure of the outcome of any interaction. message Outcome { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The name of the next state. string destination_state = 1; @@ -833,6 +946,7 @@ message Outcome { // Structure for a single hint message Hint { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The content of the hint. SubtitledHtml hint_content = 1; @@ -840,6 +954,7 @@ message Hint { // Common fields for all solutions. message BaseSolution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The explanation of the solution. SubtitledHtml explanation = 1; @@ -847,6 +962,7 @@ message BaseSolution { // Convenience collection object for all potential types of solutions. message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The different type of interactions existed in an exploration. oneof interaction_type { @@ -873,6 +989,7 @@ message Solution { // https://github.com/oppia/oppia/blob/896466ae8b/core/templates/pages/exploration-editor-page/ // editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 message Misconception { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The id of the skill. string skill_id = 1; diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index e4e196b..c7465b6 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -3,16 +3,16 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; import "org/oppia/proto/v1/structure/image.proto"; -import "org/oppia/proto/v1/structure/versions.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// NOTE: Update TopicSummaryProtoVersion if the structure of this proto is modified. The current -// version is 1. // Structure for a single topic summary. message TopicSummary { - TopicSummaryProtoVersion proto_version = 1; + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; + + org.oppia.proto.v1.versions.TopicSummaryProtoVersion proto_version = 1; // The id of the topic. string id = 2; @@ -26,8 +26,8 @@ message TopicSummary { // A list of story summaries related to this TopicSummary. repeated StorySummary story_summaries = 5; - // A list of all the subtopic indexes contained in this topic. - repeated int32 subtopic_indexes = 6; + // A list of all subtopics corresponding to this topic. + repeated SubtopicSummary subtopic_summaries = 6; // The thumbnail image corresponding to this topic. Thumbnail thumbnail = 7; // TODO @@ -41,6 +41,7 @@ message TopicSummary { // Structure of a single story summary. message StorySummary { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The id of the story. string id = 1; @@ -63,6 +64,7 @@ message StorySummary { // Structure of a single chapter summary. message ChapterSummary { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The thumbnail image for this chapter. Thumbnail thumbnail = 1; // TODO @@ -79,6 +81,7 @@ message ChapterSummary { // Structure of a single subtopic summary. message SubtopicSummary { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The index of the subtopic (within its correspnoding topic). int32 index = 1; @@ -92,6 +95,7 @@ message SubtopicSummary { // Structure of a single skill summary. message SkillSummary { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The id of the skill. string id = 1; diff --git a/proto/v1/structure/versions.proto b/proto/v1/structure/versions.proto deleted file mode 100644 index cb60109..0000000 --- a/proto/v1/structure/versions.proto +++ /dev/null @@ -1,47 +0,0 @@ -syntax = "proto3"; - -package org.oppia.proto.v1.structure; - -option java_package = "org.oppia.proto.v1.structure"; -option java_multiple_files = true; - -// The version of the TopicSummary proto. -message TopicSummaryProtoVersion { - int32 version = 1; -} - -// The version of the RevisionCard proto. -message RevisionCardProtoVersion { - int32 version = 1; -} - -// The version of the ConceptCard proto. -message ConceptCardProtoVersion { - int32 version = 1; -} - -// The version of the Exploration proto. -message ExplorationProtoVersion { - int32 version = 1; -} - -// The version of the Question proto. -message QuestionProtoVersion { - int32 version = 1; -} - -// This version implies interaction compatibility since interactions are tightly defined in the -// structures. The version of the State proto. -message StateProtoVersion { - int32 version = 1; -} - -// The version of the Language proto. -message LanguageProtosVersion { - int32 version = 1; -} - -// The version of the Image proto. -message ImageProtoVersion { - int32 version = 1; -} diff --git a/proto/v1/versions/BUILD.bazel b/proto/v1/versions/BUILD.bazel new file mode 100644 index 0000000..f25150b --- /dev/null +++ b/proto/v1/versions/BUILD.bazel @@ -0,0 +1,22 @@ +""" +TODO +""" + +load("@rules_proto//proto:defs.bzl", "proto_library") + +proto_library( + name = "versions_proto", + srcs = [ + "api_versions.proto", + "structure_versions.proto", + ], + strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. + import_prefix = "org/oppia/proto/v1/versions", # Make directory prefix match declared package. + visibility = [ + "//:api_visibility", + "//:proto_impl_visibility", + ], + deps = [ + "@com_google_protobuf//:descriptor_proto", + ], +) diff --git a/proto/v1/versions/api_versions.proto b/proto/v1/versions/api_versions.proto new file mode 100644 index 0000000..c501654 --- /dev/null +++ b/proto/v1/versions/api_versions.proto @@ -0,0 +1,37 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.versions; + +import "google/protobuf/descriptor.proto"; + +option java_package = "org.oppia.proto.v1.versions"; +option java_multiple_files = true; + +// Custom options. Note that these do not actually enforce semantics--they're +// just hints. Implementation code is expected to define the actual versioning +// semantics. See the README for more details. +extend google.protobuf.MessageOptions { + // Defines the version type corresponding to an API proto. + ApiProtoVersionType api_proto_version_type = 2000; +} + +// The only currently-supported proto version for the TopicListRequestResponse. +message TopicListRequestResponseProtoVersion { + option (api_proto_version_type) = UNVERSIONED_API_PROTO; + + int32 version = 1; +} + +// The only currently-supported proto version for the TopicContentRequestResponse. +message TopicContentRequestResponseProtoVersion { + option (api_proto_version_type) = UNVERSIONED_API_PROTO; + + int32 version = 1; +} + +enum ApiProtoVersionType { + API_PROTO_VERSION_TYPES_UNSPECIFIED = 0; + UNVERSIONED_API_PROTO = 1; + TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION = 2; + TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION = 3; +} diff --git a/proto/v1/versions/structure_versions.proto b/proto/v1/versions/structure_versions.proto new file mode 100644 index 0000000..73865d7 --- /dev/null +++ b/proto/v1/versions/structure_versions.proto @@ -0,0 +1,86 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.versions; + +import "google/protobuf/descriptor.proto"; + +option java_package = "org.oppia.proto.v1.versions"; +option java_multiple_files = true; + +// Custom options. Note that these do not actually enforce semantics--they're +// just hints. Implementation code is expected to define the actual versioning +// semantics. See the README for more details. +extend google.protobuf.MessageOptions { + // Defines the version type corresponding to a structure proto. + StructureProtoVersionType structure_proto_version_type = 1000; +} + +// The version of the TopicSummary proto. +message TopicSummaryProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the RevisionCard proto. +message RevisionCardProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the ConceptCard proto. +message ConceptCardProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the Exploration proto. +message ExplorationProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the Question proto. +message QuestionProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// This version implies interaction compatibility since interactions are tightly defined in the +// structures. The version of the State proto. +message StateProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the Language proto. +message LanguageProtosVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +// The version of the Image proto. +message ImageProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + int32 version = 1; +} + +enum StructureProtoVersionType { + STRUCTURE_PROTO_VERSION_TYPES_UNSPECIFIED = 0; + UNVERSIONED_STRUCTURE_PROTO = 1; + TOPIC_SUMMARY_PROTO_VERSION = 2; + REVISION_CARD_PROTO_VERSION = 3; + CONCEPT_CARD_PROTO_VERSION = 4; + EXPLORATION_PROTO_VERSION = 5; + QUESTION_PROTO_VERSION = 6; + STATE_PROTO_VERSION = 7; + LANGUAGE_PROTOS_VERSION = 8; + IMAGE_PROTO_VERSION = 9; +} From cdd8c6778cf8828c746afbee023da0c62d237795 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 15 Oct 2021 00:14:17 -0700 Subject: [PATCH 28/51] Redo a LOT of documentation. Essentially all documentation has been rewritten except for objects.proto & the README. These will come in later commits. This also introduces some structural changes or issues I noticed along the way. There are more needed, and two new TODOs were added to track these (for subsequent commits). Finally, this includes a lot of changes to address nearly all remaining reviewer comments that haven't already been addressed, except for those pertaining to the README. --- BUILD | 10 +- WORKSPACE | 2 +- proto/BUILD | 4 +- proto/v1/BUILD | 2 +- proto/v1/api/BUILD | 6 +- proto/v1/api/android.proto | 261 +++++-- proto/v1/structure/BUILD | 5 +- proto/v1/structure/concept_card.proto | 36 +- proto/v1/structure/exploration.proto | 21 +- proto/v1/structure/image.proto | 33 +- proto/v1/structure/languages.proto | 165 +++-- proto/v1/structure/objects.proto | 21 +- proto/v1/structure/question.proto | 13 +- proto/v1/structure/revision_card.proto | 39 +- proto/v1/structure/state.proto | 759 +++++++++++++-------- proto/v1/structure/topic_summary.proto | 77 ++- proto/v1/versions/BUILD.bazel | 3 +- proto/v1/versions/api_versions.proto | 26 +- proto/v1/versions/structure_versions.proto | 99 ++- repo/BUILD | 4 +- repo/deps.bzl | 16 +- repo/toolchains.bzl | 15 +- 22 files changed, 1046 insertions(+), 571 deletions(-) diff --git a/BUILD b/BUILD index 38de2a3..993d07a 100644 --- a/BUILD +++ b/BUILD @@ -1,5 +1,7 @@ """ -TODO: fill in +Top-level definitions for Oppia's proto API project. Only libraries that are part of the project's +public, importable API should be defined here (and all such libraries should be defined here and +nowhere else). """ load("@rules_proto//proto:defs.bzl", "proto_library") @@ -19,7 +21,9 @@ package_group( ], ) -# Note that 'deps' specifically needs to be used (versus just 'exports') since downstream +# The protos needed to interact with Oppia's proto API. This is meant to be used in cases when these +# protos are used by domain-specific protos in downstream projects. +# NOTE TO DEVELOPERS: 'deps' specifically needs to be used (versus just 'exports') since downstream # proto_library targets otherwise won't pull in the protos, and language libraries need it to # actually generate corresponding proto code. proto_library( @@ -32,12 +36,14 @@ proto_library( ], ) +# The Java versions of the protos needed to interact with Oppia's proto API. java_proto_library( name = "android_java_protos", visibility = ["//visibility:public"], deps = [":android_protos"], ) +# The Java lite versions of the protos needed to interact with Oppia's proto API. java_lite_proto_library( name = "android_java_lite_protos", visibility = ["//visibility:public"], diff --git a/WORKSPACE b/WORKSPACE index 651582c..b7156f6 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -1,5 +1,5 @@ """ -This file lists and imports all external dependencies needed to build Oppia Proto API. +The top-level WORKSPACE definition for the Oppia proto API Bazel workspace. """ load("//repo:deps.bzl", "initializeDepsForWorkspace") diff --git a/proto/BUILD b/proto/BUILD index d0f4e48..97b9d69 100644 --- a/proto/BUILD +++ b/proto/BUILD @@ -1,3 +1,5 @@ """ -TODO: fill in +The top-level directory for the Oppia proto API. Generally, no actual proto libraries should be +defined at this level. Instead, protos should go into the corresponding version in which they +belong. See the README for more details on the API is versioned. """ diff --git a/proto/v1/BUILD b/proto/v1/BUILD index d0f4e48..845543b 100644 --- a/proto/v1/BUILD +++ b/proto/v1/BUILD @@ -1,3 +1,3 @@ """ -TODO: fill in +Version 1 of the Oppia proto API. See the README for specifics on how the API is versioned. """ diff --git a/proto/v1/api/BUILD b/proto/v1/api/BUILD index b102549..2e4da12 100644 --- a/proto/v1/api/BUILD +++ b/proto/v1/api/BUILD @@ -1,9 +1,5 @@ """ -This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. -The proto_library() rule creates a proto file library for the android API -proto file to be used in multiple languages. -The java_lite_proto_library() rule takes in a proto_library target and generates Java code. -The java_proto_library() rule takes in a proto_library target and generates Java code. +Libraries that define endpoint API protos for interacting with Oppia's backend. """ load("@rules_proto//proto:defs.bzl", "proto_library") diff --git a/proto/v1/api/android.proto b/proto/v1/api/android.proto index 30fb53e..842e751 100644 --- a/proto/v1/api/android.proto +++ b/proto/v1/api/android.proto @@ -13,26 +13,54 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.api"; option java_multiple_files = true; -// The proto request made to the server to get the list of topics which are available for download. +// A request for the list of topics available to a local client. +// +// Note that the backend is principally responsible for providing the client with exact content +// versions and structure IDs that are compatible with that client. For the most part, this involves +// ensuring that the returned proto structures match the requested proto structures (and for cases +// when that's not possible, such as if a new interaction is introduced, the corresponding topic +// will not be provided as an available topic for downloading or updating). +// +// Another dimension of compatibility is the list of supported languages. For an optimal user +// experience, the backend won't provide the client with topics or topic updates that aren't fully +// localized to the languages expected by the client. +// TODO(#5): Update the API to properly account for written translation packs. message TopicListRequest { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; - // The common proto version defining this request/response pair. + // The common proto version defining this request/response pair. Note that the response may be + // provided with a different version since it should match the requested proto version defined + // below. The request can use any version at the choice of the client since the server guarantees + // full backward compatibility for all proto structure versions. org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion proto_version = 1; - // Details about the Android app client that is making the request. - ClientContext client_context = 2; - // Details about the latest proto versions that this Android client can support. + // Details about the client that is making the request. + AndroidClientContext client_context = 2; + + // Details about the latest proto versions that this client can support. The server is expected to + // only provide structures that exactly match the proto versions provided. ClientCompatibilityContext compatibility_context = 3; - // TODO: Fill this in. - repeated VersionedStructureMetadata current_downloads_context = 4; + + // The current structures that are downloaded by the local client. Note that this must be a + // comprehensive list of downloaded structures in order to leverage certain consistency guarantees + // by the backend, including ensuring that structures are never re-downloaded or violate the + // one-version expectation (that is, only the latest compatible version of a shared cross-topic + // structure is downloaded and never multiple versions of it). + // + // Note also that all returned structures are expected to be localized to English by default with + // optional additional language localizations available (as limited by the languages proto + // version which denotes which languages are currently supported by the API). + repeated VersionedStructureDetails current_downloads_context = 4; } -// The expected proto response from the server when provided with a TopicListRequest. +// TODO: add support for upcoming topics, for the topic graph ordering, and for topics that can't be downloaded/updated (to provide notices to the user). + +// The expected response from the server when provided with a TopicListRequest. message TopicListResponse { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; - // The common proto version defining this request/response pair. + // The common proto version defining this request/response pair. This is expected to match the + // version provided in the compatibility context included in the topic list request. org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion proto_version = 1; // A list of all topics that are compatibly available to the client whose context corresponds to @@ -75,7 +103,7 @@ message TopicListResponse { // The full summary for the current topic. Note that this will be absent if the local client // already has the latest summary downloaded as indicated by its download state context. - org.oppia.proto.v1.structure.TopicSummary topic_summary = 2; + org.oppia.proto.v1.structure.DownloadableTopicSummary topic_summary = 2; // The size, in bytes, needed to download the topic. uint32 download_size_bytes = 3; @@ -106,7 +134,7 @@ message TopicListResponse { // an incremental update to minimize the download work & bandwidth needed by the local client. // update_size_bytes will reflect the data determined by the server to be needed to update the // topic. - repeated VersionedStructureMetadata updated_structures = 4; + repeated VersionedStructureDetails updated_structures = 4; } // Represents a topic that's been downloaded by the local client and is fully up-to-date. @@ -123,138 +151,241 @@ message TopicListResponse { } } -// The proto request made to the server to get the latest still-compatible content for specific -// topics. +// The request made to the server to get the latest compatible content for specific topics. This +// request is designed such that any number of structures may be requested to download along with a +// max payload size, and multiple requests can be set in parallel and at any time. Together, this +// enables pagination-based retrieval and download pausing/restarting in clients, if either feature +// is needed by the client. message TopicContentRequest { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion proto_version = 1; - // Details about the Android app client that is making the request. - ClientContext client_context = 2; - // The IDs of the entities making up the topic whose data is to be fetched. + // Details about the client that is making the request. + AndroidClientContext client_context = 2; + + // Specific structure identifiers that should be fetched, preferably in the order of the list. + // Note that the server only aims to prioritize earlier items in the list, but does not guarantee + // that they will be delivered if other factors affect sending a response for a particular item + // (such as the max payload size or a particular structure not existing). Note that no effort is + // made to ensure compatibility between the local client and the requested structures; the client + // is expected to make this determination based on the structure content & proto versions received + // from the topic list API. Finally, duplicates will be ignored to avoid repeating the same data + // multiple times. repeated DownloadRequestStructureIdentifier identifiers = 3; - // The maximum payload size that the server should furnish as a single download operation. This is - // only a request, and may not be honoured by the server (which will only adhere to this field on - // a best-effort basis). - int32 requested_max_payload_size = 4; + + // The maximum payload size, in bytes, that the server should furnish as a single download + // operation. This is only a request, and may not be honoured by the server (which will only + // adhere to this field on a best-effort basis). This is calculated by taking the wire byte size + // (without compression) corresponding to a computed response (though the server may use estimates + // for efficiency, and will guarantee that the estimate isn't far off from the actual size sent). + uint32 requested_max_payload_size_bytes = 4; } -// The expected proto response from the server when provided with a TopicContentRequest. +// The expected response from the server when provided with a TopicContentRequest. message TopicContentResponse { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion proto_version = 1; - // A list of the individual items to be downloaded. + // A list of the individual items that were downloaded. Items in this list are expected to be + // relatively in the same order as the identifiers in the request, but some items may be missing + // (see the request's documentation for details). Note also that these will never include external + // assets such as voiceovers or images--those always must be downloaded separately. repeated DownloadResult download_results = 2; - // The result of downloading a specific asset. This may either contain the result of the download, - // or an indication that the download was skipped. + // The result of downloading a specific structure. This may either contain the result of the + // download, or an indication that the download was skipped and roughly why. The potential results + // correspond to the download requests that can be made per DownloadRequestStructureIdentifier. message DownloadResult { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; - // The entity type and ID corresponding to this download. + // The entity type and ID corresponding to this download. This is guaranteed to exactly match at + // least one of the original identifiers in the request. DownloadRequestStructureIdentifier identifier = 1; - oneof structure_type { + // The type/nature of the download result (see fields for specifics). + oneof result_type { // The presence of this value indicates that the request corresponding to this particular // identifier was skipped and suggested to retry by the Oppia backend. Note that the presence // of this value in the oneof is sufficient to indicate its state; its actual value does not // matter. - bool skipped = 2; - org.oppia.proto.v1.structure.TopicSummary topic_summary = 3; - org.oppia.proto.v1.structure.RevisionCard revision_card = 4; - org.oppia.proto.v1.structure.ConceptCard concept_card = 5; - org.oppia.proto.v1.structure.Exploration exploration = 6; - QuestionIdList question_id_list = 7; - org.oppia.proto.v1.structure.Question question = 8; + bool skipped_should_retry = 2; + + // The presence of this value indicates that the request outright failed for this particular + // identifier, potentially due to incorrect version/identifier information or an internal + // server failure. It is not recommended to retry the request since it's expected to fail + // again. Note that the presence of this value in the oneof is sufficient to indicate its + // state; its actual value does not matter. Note also that this is different than an HTTP + // error since certain error codes can be retried (in those cases, the entire response is + // expected to fail rather than a particular item within the response). + bool skipped_from_failure = 3; + + // The result is a requested topic summary. + org.oppia.proto.v1.structure.DownloadableTopicSummary topic_summary = 4; + + // The result is a requested revision card. + org.oppia.proto.v1.structure.RevisionCard revision_card = 5; + + // The result is a requested concept card. + org.oppia.proto.v1.structure.ConceptCard concept_card = 6; + + // The result is a requested exploration. + org.oppia.proto.v1.structure.Exploration exploration = 7; + + // The result is a requested list of question IDs. + QuestionIdList question_id_list = 8; + + // The result is a requested question. + org.oppia.proto.v1.structure.Question question = 9; } } - // A list of question IDs corresponding to the topic. + // A list of question IDs that directly correspond to a particular skill ID. message QuestionIdList { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; - // The list of question IDs. + // The list of question IDs that correspond to a particular skill ID. repeated string question_ids = 1; } } -// TODO: Add docs. -message ClientContext { +// Represents the Oppia Android client that's making a request to Oppia's backend. This message +// includes metadata to help the backend understand the specific client that's connecting (generally +// for enabling certain platform parameters, checking for app deprecation, adjusting response +// protocols if necessary, and for telemetry). +message AndroidClientContext { option (org.oppia.proto.v1.versions.api_proto_version_type) = UNVERSIONED_API_PROTO; - // TODO: Add doc and clarify name. - string version_name = 1; - // TODO: Add doc and clarify name. - int64 version_code = 2; + // The app version name corresponding to the locally installed Android client. For more + // information, see: https://developer.android.com/studio/publish/versioning#appversioning. + string app_version_name = 1; + + // The app version code corresponding to the locally installed Android client. For more + // information, see: https://developer.android.com/studio/publish/versioning#appversioning. + uint64 app_version_code = 2; } -// Information about the latest proto versions that the client can support. -// TODO: Clarify whether, if a client can support version N, this means it can support -// versions 1 to N, or only version N. If neither of these, then we might need a -// "from ... to" range for each field, rather than a single version. Note for future documentation -// iteration: clients only guarantee exact support. Onus is on the server to supply the exact proto -// structure version for client compatibility (which should always be possible per design of proto). +// Information about the latest proto versions that the client can support. The client is expected +// to only support responses & response contents that match the exact versions provided in this +// message, but it's permitted to send requests using any valid proto version for the request +// structure. The backend is expected to always structure responses accordingly to the requested +// versions provided here. message ClientCompatibilityContext { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + // The latest proto version for topic list responses that the client can support. + org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion topic_list_request_response_proto_version = 1; + + // The latest proto version for topic content responses that the client can support. + org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion topic_content_request_response_proto_version = 2; + // The latest proto version for topic summaries that the client can support. - org.oppia.proto.v1.versions.TopicSummaryProtoVersion topic_summary_proto_version = 1; + org.oppia.proto.v1.versions.TopicSummaryProtoVersion topic_summary_proto_version = 3; + // The latest proto version for revision cards that the client can support. - org.oppia.proto.v1.versions.RevisionCardProtoVersion revision_card_proto_version = 2; + org.oppia.proto.v1.versions.RevisionCardProtoVersion revision_card_proto_version = 4; + // The latest proto version for concept cards that the client can support. - org.oppia.proto.v1.versions.ConceptCardProtoVersion concept_card_proto_version = 3; + org.oppia.proto.v1.versions.ConceptCardProtoVersion concept_card_proto_version = 5; + // The latest proto version for explorations that the client can support. - org.oppia.proto.v1.versions.ExplorationProtoVersion exploration_proto_version = 4; + org.oppia.proto.v1.versions.ExplorationProtoVersion exploration_proto_version = 6; + // The latest proto version for questions that the client can support. - org.oppia.proto.v1.versions.QuestionProtoVersion question_proto_version = 5; + org.oppia.proto.v1.versions.QuestionProtoVersion question_proto_version = 7; + // The latest proto version for states that the client can support. - org.oppia.proto.v1.versions.StateProtoVersion state_proto_version = 6; + org.oppia.proto.v1.versions.StateProtoVersion state_proto_version = 8; + // The latest proto version for language-related protos that the client can support. - org.oppia.proto.v1.versions.LanguageProtosVersion language_protos_version = 7; + org.oppia.proto.v1.versions.LanguageProtosVersion language_protos_version = 9; + // The latest proto version for images that the client can support. - org.oppia.proto.v1.versions.ImageProtoVersion thumbnail_proto_version = 8; + org.oppia.proto.v1.versions.ImageProtoVersion thumbnail_proto_version = 10; } -// TODO: Document this fully. -message VersionedStructureMetadata { +// Details about a versione dstructure that's compatible with the local client. This can be used +// both to indicate the local download state of a client's topics, and to provide details for +// available changes to client-compatible topics. +// +// Note also that all structures represented by this message are considered "global" (that is, not +// tied to any particular topics) even though this message may be used in the context of a topic +// (generally to represent structures corresponding to the learning experience provided by that +// topic). This is an important distinction since some structures (like concept cards) aren't +// actually tied to any particular topics, and can be used across multiple topics. However, they are +// downloaded with the first topic that references them, and shouldn't be re-downloaded in +// subsequent topics (the backend makes guarantees to ensure that structures are never repeated). +message VersionedStructureDetails { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; - int32 content_version = 1; + // The backend-tracked and creator-affected content version of the structure. This is the primary + // indicator of how "new" a particular structure is, or whether it has updates available. This is + // always a monotonically increasing positive integer for newer versions. + uint32 content_version = 1; + + // The type of structure being detailed. oneof structure_type { + // Indicates that these details correspond to a complete topic, as specified by its ID. string topic_id = 2; + + // Indicates that these details correspond to a topic summary, as specified by a topic ID. string topic_summary_id = 3; + + // Indicates that these details correspond to a revision card, as specified by its ID structure. org.oppia.proto.v1.structure.SubtopicId revision_card_id = 4; + + // Indicates that these details correspond to a concept card, as specified by its skill ID. string concept_card_id = 5; + + // Indicates that these details correspond to a story, as specified by its ID. string story_id = 6; + + // Indicates that these details correspond to an exploration, as specified by its ID. string exploration_id = 7; + + // Indicates that these details correspond to a question, as specified by its ID. string question_id = 8; + + // Indicates that these details correspond to a skill, as specified by its ID. string skill_id = 9; } } -// The type and ID of a specific asset that is being downloaded. +// An identifier used to download a specific structure at a particular content version as part of +// the topic content API. It's expected that the server-provided structure will utilize the provided +// proto version requested by the client. +// +// Note that there is a special caveat on the "global-ness" of the identifiers reference here. See +// VersionedStructureDetails for more details as it shares the same caveat. message DownloadRequestStructureIdentifier { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; + // The content (creator-affected) version of the request. See the similar field in + // VersionedStructureDetails for more details on what this value represents. uint32 content_version = 1; + // The type of structure being requested for downloading. oneof structure_type { + // Indicates that a topic summary should be downloaded, as specified by a topic ID. string topic_summary_id = 2; - // The ID of the revision card ("subtopic") to be downloaded. + + // Indicates that a revision card ("subtopic") should be downloaded, as specified by its ID. org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; - // The ID of the concept card to be downloaded. + + // Indicates that a concept card should be downloaded, as specified by its skill ID. string concept_card_id = 4; - // The ID of the exploration to be downloaded. + + // Indicates that an exploration should be downloaded, as specified by its ID. string exploration_id = 5; - // The skill ID whose associated questions are to be downloaded. - // TODO: Clarify difference between this and concept_card_id above (field 2). + + // Indicates that the list of questions associated with a specific skill ID should be + // downloaded, as specified by that ID. string question_list_skill_id = 6; - // The ID of the question to be downloaded. + + // Indicates that a question should be downloaded, as specified by its ID. string question_id = 7; } } diff --git a/proto/v1/structure/BUILD b/proto/v1/structure/BUILD index 5a29aac..44cdea0 100644 --- a/proto/v1/structure/BUILD +++ b/proto/v1/structure/BUILD @@ -1,8 +1,5 @@ """ -This library contains the proto_library(), java_lite_proto_library() and java_proto_library rules. -The proto_library() rule creates a proto file library for the core proto files to be used in multiple languages. -The java_lite_proto_library() rule takes in a proto_library target and generates Java code. -The java_proto_library() rule takes in a proto_library target and generate Java code. +Libraries that define core lesson structure protos. """ load("@rules_proto//proto:defs.bzl", "proto_library") diff --git a/proto/v1/structure/concept_card.proto b/proto/v1/structure/concept_card.proto index c73645c..583b4df 100644 --- a/proto/v1/structure/concept_card.proto +++ b/proto/v1/structure/concept_card.proto @@ -9,43 +9,51 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single concept card that can be displayed for a specific skill. +// Represents a single concept card that can be displayed for a specific skill. Skills are expected +// to have exactly one concept card associated with them. Concept cards provide a lightweight +// reminder experience for learners that can help them get unstuck when they might have forgotten +// aspects of a certain skill that they need to demonstrate in a practice session or exploration. message ConceptCard { option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; - // The proto version defining the internal structure of this concept card proto message. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ConceptCardProtoVersion proto_version = 1; // The ID corresponding to the skill this concept is representing. string skill_id = 2; - //A human-readable description for the skill. + // A human-readable description for the skill. This is expected to be in English. string description = 3; - // The explanation of the skill that is shown in the concept card. - SubtitledHtml explanation = 4; + // The localizable explanation of the skill that is to be shown in the concept card. + SubtitledText explanation = 4; // A list of worked examples to present to the learner. repeated WorkedExample worked_examples = 5; - // The recorded voiceovers for SubtitledHtml subfields of this concept card. + // The recorded voiceovers for SubtitledText subfields of this concept card. RecordedVoiceovers recorded_voiceovers = 6; - // The translations of SubtitledHtml subfields of this concept card. + // The translations of SubtitledText subfields of this concept card. WrittenTranslations written_translations = 7; - // The list of all images that are included within SubtitledHtml subfields of this concept card. + // The list of all images that are included within SubtitledText subfields of this concept card. + // This is expected to include all references images, including in translations. ReferencedImageList referenced_image_list = 8; - // Each worked example provides a sample question and answer for the student to read and learn - // from. + // The version of the contents of this concept card (which corresponds to the 'version' field for + // the concept card's skill on the server). + uint32 content_version = 9; + + // Represents a worked example (which provides a sample question and answer for the learner to + // read and learn from). message WorkedExample { option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; - // The question for this worked example. - SubtitledHtml question = 1; + // The localizable question for this worked example. + SubtitledText question = 1; - // The explanation for how to solve this worked example. - SubtitledHtml explanation = 2; + // The localizable explanation for how to solve this worked example. + SubtitledText explanation = 2; } } diff --git a/proto/v1/structure/exploration.proto b/proto/v1/structure/exploration.proto index 4bc6bf0..2d9d84c 100644 --- a/proto/v1/structure/exploration.proto +++ b/proto/v1/structure/exploration.proto @@ -9,29 +9,32 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single exploration. +// Represents a single exploration that can be played by a learner. Explorations are interactive +// lessons that are meant to teach or build on specific skills. message Exploration { option (org.oppia.proto.v1.versions.structure_proto_version_type) = EXPLORATION_PROTO_VERSION; - // The proto version defining the internal structure of this exploration proto message. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ExplorationProtoVersion proto_version = 1; // The ID of the exploration. string id = 2; - // The title of the exploration. + // The human-readable title of the exploration. This is expected to be in English. string title = 3; - // The name of the initial state of the exploration. + // The name of the initial state of the exploration. This corresponds to keys in the 'states' + // field. string init_state_name = 4; - // The mapping from state names to state objects. + // The mapping from state names to state objects. State names are not meant to be + // learner-readable. map states = 5; - // The version of the contents of this exploration. (This corresponds to the 'version' field on - // the server.) - int32 content_version = 6; + // The version of the contents of this exploration (which corresponds to the 'version' field on + // the server). + uint32 content_version = 6; - // A list of all the images contained in SubtitledHtml subfields of this exploration. + // A list of all the images contained in SubtitledText subfields of this exploration. ReferencedImageList referenced_image_list = 7; } diff --git a/proto/v1/structure/image.proto b/proto/v1/structure/image.proto index dd562d8..a315223 100644 --- a/proto/v1/structure/image.proto +++ b/proto/v1/structure/image.proto @@ -7,27 +7,44 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single thumbnail image. +// Represents a single thumbnail image that may be shown for various lesson structures (including +// topics, stories, chapters, and revision cards). Note that while this message doesn't define a +// particular image resolution, it's expected that: +// - Topic and story thumbnails should work in both 4:3 and 16:9 contexts +// - Revision card thumbnails should work in 4:3 contexts +// - Chapter (exploration) thumbnaisl should work in 16:9 contexts +// - All other thumbnails should default to 4:3 (since that can be made workable to 16:9) message Thumbnail { option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; - // The proto version defining the internal structure of this image proto message. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; - // The name of the thumbnail image file. + // The name of the thumbnail image file. This will never be a URL (and can always be expected to + // just be a filename). The image is stored in GCS static file storage and must be downloaded + // separately by the client. The client can expect that this image is immutable on the server. + // Further, the client can also assume that all images are one of three formats: + // - PNG (indicated with a .png extension) + // - WebP (indicated with a .webp extension) + // - SVG (indicated with a .svg extension) string filename = 2; - // The background color to be shown behind the thumbnail image. - int32 background_color_rgb = 3; + // The RGB background color to be shown behind the thumbnail image. Note that this is given in + // RGB888 format, following local endianness (which is automatically handled by protobuf). There + // is never expected to be an alpha component on this color, but it's also not guaranteed that the + // upper 8 bits will be zeroed (so it's recommended to always mask those out when extracting the + // red component of the color, or when treating it as a proper RGB value). + uint32 background_color_rgb = 3; } -// Proto representing a list of images. +// Represents a list of images that may be referenced by various topic structures. message ReferencedImageList { option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; - // The proto version defining the internal structure of this list of images. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; - // The list of filenames of all the images in the list. + // The list of filenames of all the images in the list. See the 'filename' field in Thumbnail for + // specifics on the expected values of these filenames. repeated string referenced_image_filenames = 2; } diff --git a/proto/v1/structure/languages.proto b/proto/v1/structure/languages.proto index 6e983a6..cff5cf9 100644 --- a/proto/v1/structure/languages.proto +++ b/proto/v1/structure/languages.proto @@ -7,144 +7,167 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// A list of languages supported by the Android app. -enum Language { - // TODO: Add docstring to explain why this is needed and when it should be used. +// NOTE: many of the structures in this file share a common LanguageProtosVersion version. See the +// documentation on that structure for details as to why. + +// The language types supported by this API. These are used both for content string localization and +// to represent voiceover subtitles. Note that any changes to this structure will correspond to +// changes to LanguageProtosVersion (similar to the proto structures that use this version below). +// Note also that from a design perspective, languages should always be represented using this as a +// strong type rather than string-based language codes which can introduce support issues and +// inconsistencies. +enum LanguageType { + option (org.oppia.proto.v1.versions.structure_enum_version_type) = LANGUAGE_PROTOS_VERSION; + + // The default language. This generally corresponds to cases when a language isn't defined, is + // unsupported, or it's not known whether the language is supported. Clients are expected to + // default to no-op behaviors when they encounter this language type. LANGUAGE_CODE_UNSPECIFIED = 0; + + // Corresponds to general English (that is, not particularly regionally tied). This is the assumed + // default language for all content strings. ENGLISH = 1; + + // Corresponds to general Arabic (that is, not particularly regionally tied). ARABIC = 2; + + // Corresponds to general Hindi (that is, not particularly regionally tied). HINDI = 3; + + // Corresponds to the macaronic language Hinglish which combines Hindi and English. This + // corresponds to a generic 'Hinglish' which combines localisms from different areas, but is not + // predominantly tied to a particular region. HINGLISH = 4; + + // Corresponds to a regional Portuguese that's primarily used in Brazil. BRAZILIAN_PORTUGUESE = 5; } -// Proto message representing a block of (subtitled) HTML. -message SubtitledHtml { +// Represents a block of (subtitled) text. This structure is used for content strings so that they +// may be supplemented with audio translations, or localized by replacing the text string with a +// language-specific translation of it. +// +// Note that this represents both ASCII & Unicode HTML & plain text strings, and combines two +// different Oppia's backend structures ('SubtitledHtml' and 'SubtitledUnicode'). Protobuf takes +// care of properly representing Unicode strings internally by using UTF-8 encoding, so no special +// care is needed by implementations or clients. +message SubtitledText { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The proto version defining the internal structure of this proto message. - // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; - // The content ID for this SubtitledHtml. This is unique within a State. + // The content ID for this text that can be used to retrieve a voiceover or translation + // representation of this text. This ID is unique in its local context (e.g. a 'State' for + // subtitled texts used within states). string content_id = 2; - // The HTML content of the SubtitledHtml. - string html = 3; + // The user-readable HTML/plain text content (which may be in Unicode). This is expected to always + // be in English, and in situations where non-English variants are desired the content ID should + // be matched to a language-specific translation (see WrittenTranslations for details). + string text = 3; } -// Proto message representing recorded voiceovers. +// Represents a group of voiceovers that correspond to subtitled texts in a particular content +// context (such as a revision card or a 'State' in an exploration). message RecordedVoiceovers { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The proto version defining the internal structure of this proto message. - // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; - // A list of mappings from language codes to voiceover bundles (which each map individual - // SubtitledHtml content IDs to their voiceovers in that language). - repeated VoiceoverContentMapping voiceover_language_mapping = 2; + // A list of mappings from language to voiceover content mappings (see the message's documentation + // for specifics on the latter). + repeated VoiceoverContentMapping voiceover_content_mapping = 2; } -// Proto message mapping SubtitledHtml fields to their corresponding voiceovers for a particular -// language. +// Represents a mapping of SubtitledText content IDs to voiceovers for a particular language. message VoiceoverContentMapping { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The language that this mapping is for. - Language language = 1; + // The language corresponding to this mapping. + LanguageType language = 1; - // The mapping of content IDs to their corresponding voiceover files. - map voiceover_content_mapping = 2; + // The mapping of SubtitledText content IDs to their corresponding voiceover files. + map voiceover_content_mapping = 2; } -// Proto message representing a specific voiceover file. -message Voiceover { +// Represents an audio file that, when played, reads out content text in a particular language. +message VoiceoverFile { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The file name of the voiceover. + // The name of the voiceover audio file. This will never be a URL (and can always be expected to + // just be a filename). The audio file is stored in GCS static file storage and must be downloaded + // or streamed separately by the client. The client can expect that this file is immutable on the + // server. Further, the client can also assume that all audio files are always of the format MP3. + // There's no support for transcoding audio at a given bitrate, it's always fixed based on the + // uploaded bitrate (as managed by Oppia's backend). string filename = 1; // The size of the voiceover file, in bytes. - int32 file_size_bytes = 2; + uint32 file_size_bytes = 2; - // The duration of the voiceover, in seconds. + // The duration of the voiceover audio track, in seconds. float duration_secs = 3; } -// Proto message representing a set of written translations. +// Represents a group of written translations that correspond to subtitled texts in a particular +// content context (such as a revision card or a 'State' in an exploration). message WrittenTranslations { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The proto version defining the internal structure of this proto message. - // TODO: Add more explanation for why this is dependent on a common LanguageProtosVersion. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; - // A list of mappings from language codes to written translations (which each map individual - // SubtitledHtml content IDs to their written translations in that language). + // A list of mappings from language to written translation content mappings (see the message's + // documentation for specifics on the latter). repeated WrittenTranslationContentMapping translation_language_mapping = 2; } -// Proto message mapping SubtitledHtml fields to their corresponding written translations in a -// particular language. +// Represents a mapping of SubtitledText content IDs to written translations for a particular +// language. message WrittenTranslationContentMapping { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The language that this mapping is for. - Language language = 1; + // The language corresponding to this mapping. + LanguageType language = 1; - // The mapping of content IDs to their corresponding written translations. + // The mapping of SubtitledText content IDs to their corresponding written translations. map translation_content_mapping = 2; } -// Proto message representing a single written translation. +// Represents a single textual translation of specific content text in a particular language. message WrittenTranslation { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The data format of the source material for this translation. oneof data_format { - // The translation for an HTML string. - WrittenTranslatableHtml translatable_html = 1; - - // The translation for a unicode string. - WrittenTranslatableUnicode translatable_unicode = 2; - - // The translation for a set of normalized strings. - WrittenTranslatableSetOfNormalizedString translatable_set_of_normalized_string = 3; + // Indicates that this translation corresponds to a single piece of text. + WrittenTranslatableText translatable_text = 1; - // The translation for a set of unicode strings. - WrittenTranslatableSetOfUnicodeString translatable_set_of_unicode_string = 4; + // Indicates that this translation corresponds to a list of translated texts. + SetOfWrittenTranslatableText set_of_translatable_text = 2; } } -// Proto message representing the translation of a single HTML string. -message WrittenTranslatableHtml { +// Represents the translation of a single text string (which may be either plain text or HTML, and +// is generally expected to potentially contain Unicode characters). +message WrittenTranslatableText { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The human-readable translated string. string translation = 1; } -// Proto message representing the translation of a single unicode string. -message WrittenTranslatableUnicode { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - - string translation = 1; -} - -// Proto message representing the translation of a set of normalized strings. Note that such -// translations have a variable number of strings, the number of which may be different from the -// number of strings in the original set. -message WrittenTranslatableSetOfNormalizedString { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - - repeated string translation = 1; -} - -// Proto message representing the translation of a set of unicode strings. Note that such -// translations have a variable number of strings, the number of which may be different from the -// number of strings in the original set. -message WrittenTranslatableSetOfUnicodeString { +// Represents a set of translated strings. As indicated in WrittenTranslatableText, each string may +// be either plain text or HTML, and generally can be expected to contain Unicode characters. +// +// Note that while the list of translated strings roughly corresponds to the original source +// material (i.e. the default, untranslated content strings specified directly in SubtitledText), +// neither the order nor the length are expected to exactly match. +message SetOfWrittenTranslatableText { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - repeated string translation = 1; + // The list of human-readable translated strings. + repeated string translations = 1; } diff --git a/proto/v1/structure/objects.proto b/proto/v1/structure/objects.proto index 5ded563..eb04013 100644 --- a/proto/v1/structure/objects.proto +++ b/proto/v1/structure/objects.proto @@ -20,7 +20,7 @@ message Fraction { uint32 numerator = 3; // The denominator of the fraction. - int32 denominator = 4; + uint32 denominator = 4; } // Proto representing a single content ID for an HTML field. This content ID is used to map HTML @@ -40,11 +40,11 @@ message SetOfTranslatableHtmlContentIds { // Proto representing a list of SetOfTranslatableHtmlContentIds. message ListOfSetsOfTranslatableHtmlContentIds { // The sets of content IDs. - repeated SetOfTranslatableHtmlContentIds content_id_lists = 1; + repeated SetOfTranslatableHtmlContentIds content_id_sets = 1; } // Proto representing a 2D point for the ImageRegion interaction type. -message Point2d { +message NormalizedPoint2d { // Relative x-coordinate of the point within the image. This lies within the range [0, 1] and // measures horizontal distance (with the left boundary of the image as the origin). @@ -55,17 +55,6 @@ message Point2d { double y = 2; } -// Proto representing the location of a click on an image. This is for the ImageRegion interaction -// type. -message ClickOnImage { - - // The relative coordinates of the point where the user clicked on the image. - Point2d click_position = 1; - - // All the selected regions on the image. - repeated string clicked_regions = 2; -} - // Proto representing a ratio object in list form, e.g. [1,2,3] for 1:2:3. message RatioExpression { // List of components in the ratio. The list is expected to have more than one element. @@ -111,10 +100,10 @@ message ImageWithRegions { // (downwards). message NormalizedRectangle2d { // The top-left corner of the rectangle, in normalized coordinates. - Point2d upper_left = 1; + NormalizedPoint2d top_left = 1; // The bottom-right corner of the rectangle, in normalized coordinates. - Point2d lower_right = 2; + NormalizedPoint2d bottom_right = 2; } } } diff --git a/proto/v1/structure/question.proto b/proto/v1/structure/question.proto index 50536f7..36caf2d 100644 --- a/proto/v1/structure/question.proto +++ b/proto/v1/structure/question.proto @@ -9,11 +9,16 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single question. +// Represents a single question corresponding to one or more skills, to be used in practice or +// training sessions. Note that skills may have multiple questions associated with them, and a +// single question may correspond to more than one skill. +// +// Questions are not directly tied to topics, but clients are expected to initiate training sessions +// by picking questions that correspond to the skills of the topic's subtopics. message Question { option (org.oppia.proto.v1.versions.structure_proto_version_type) = QUESTION_PROTO_VERSION; - // The proto version defining the internal structure of this question proto message. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.QuestionProtoVersion proto_version = 1; // The ID of the question. @@ -26,8 +31,8 @@ message Question { repeated string linked_skill_ids = 4; // The version of the contents of this question. - int32 content_version = 5; + uint32 content_version = 5; - // The list of all images that are included within SubtitledHtml subfields of this question. + // The list of all images that are included within SubtitledText subfields of this question. ReferencedImageList referenced_image_list = 6; } diff --git a/proto/v1/structure/revision_card.proto b/proto/v1/structure/revision_card.proto index 7d64f3a..f8c48eb 100644 --- a/proto/v1/structure/revision_card.proto +++ b/proto/v1/structure/revision_card.proto @@ -9,47 +9,52 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Proto message representing a single revision card that can be displayed for a specific subtopic. -// NOTE: Update RevisionCardProtoVersion if the structure of this proto is modified. The current -// version is 1. +// Represents a revision card that can be displayed for a specific subtopic. Revision cards are +// longer reference cards for categories of skills taught by a topic, and are meant to be used on an +// ad hoc basis by learners when they need to refresh previously learned skills before starting a +// practice session or new exploration. +// +// Topics may contain one or more subtopics, but subtopics only ever belong to a single topic. +// Each subtopic always has a single corresponding revision card. message RevisionCard { option (org.oppia.proto.v1.versions.structure_proto_version_type) = REVISION_CARD_PROTO_VERSION; - // The proto version defining the internal structure of this revision card proto message. + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.RevisionCardProtoVersion proto_version = 1; - // The id of the subtopic in which this revision card is displayed. + // The structured ID of the subtopic corresponding to this revision card. SubtopicId id = 2; - // The title of the revision card. + // The human-readable title of the revision card. This is expected to be in English. string title = 3; - // The content of this revision card. - SubtitledHtml content = 4; + // The main content of this revision card. + SubtitledText content = 4; - // The recorded voiceovers for SubtitledHtml subfields of this revision card. + // The recorded voiceovers for SubtitledText subfields of this revision card. RecordedVoiceovers recorded_voiceovers = 5; - // The written translations for SubtitledHtml subfields of this revision card. + // The written translations for SubtitledText subfields of this revision card. WrittenTranslations written_translations = 6; // The thumbnail image for this revision card. Thumbnail thumbnail = 7; - // The list of all images that are included within SubtitledHtml subfields of this revision card. + // The list of all images that are included within SubtitledText subfields of this revision card. ReferencedImageList referenced_image_list = 8; } -// Proto message representing a subtopic ID. +// Represents the identifier for a subtopic (which are tightly tied to specific topics). message SubtopicId { - // This proto message type is shared among multiple parent protos, so it has no direct migration - // pathway. Changes should be carefully done, or the proto should be duplicated according to - // whichever proto requires alterations. + // This proto message type is shared among multiple protos, so it has no direct migration pathway. + // Changes here should be carefully done in a way that does not break compatibility or assumptions + // across all relevant proto versions, or the proto should be duplicated according to whichever + // proto requires alterations. option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; // The ID of the topic that contains this subtopic. string topic_id = 1; - // The index of this subtopic within its parent topic. - int32 index = 2; + // The index of this subtopic within its topic. + uint32 index = 2; } diff --git a/proto/v1/structure/state.proto b/proto/v1/structure/state.proto index eff7eb6..a8314ec 100644 --- a/proto/v1/structure/state.proto +++ b/proto/v1/structure/state.proto @@ -9,907 +9,1097 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// TODO: add customization args defaults & CI check to cross-validate them with web? - -// Proto message representing a single State. +// Represents a 'State' within a learning session (such as a practice quiz or exploration). A +// 'State' corresponds to a visual card shown to the learner with initial content (often a +// question) along with an 'interaction' (a type of answer that the user can input, such as +// fractions or text). When users submit answers to this interaction, they receive feedback in the +// form of a textual response and may be routed to the same state, or to a new state (which may be a +// repeat of one they've completed in the past). message State { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.StateProtoVersion proto_version = 1; - // The content of the state. - SubtitledHtml content = 2; + // The main content of the state which is the first thing shown to a learner viewing this state. + SubtitledText content = 2; - // The interactions of the state. + // The interaction of the state (which must be interacted with by the learner in order to + // proceed). InteractionInstance interaction = 3; - // The recorded voiceovers of the state. + // The recorded voiceovers for SubtitledText subfields of this state. RecordedVoiceovers recorded_voiceovers = 4; - // The written translations of the state. + // The translations of SubtitledText subfields of this state. WrittenTranslations written_translations = 5; } -// Structure for a single interaction. +// Represents an instance of a single interaction within a state. Note that interactions are +// specialized so that the client can perform very specific analysis on the user's answer as to +// provide more useful or targeted feedback (and to help detect specific misconceptions that the +// learner may be having). Specific interactions may also provide interaction-specific error +// messages (such as malformed fractions). +// +// Note that interactions work by matching user answers to rules that are organized into 'answer +// groups'. If an answer group is matched, the textual feedback corresponding to that group is shown +// to the user and the route defined by that group is taken (i.e. the defined state is the next +// state shown to the user). This route & the feedback are organized into a concept called an +// 'outcome'. Many interactions have 'default' outcomes that are selected if no answers match (or in +// cases when the user doesn't have choice on providing dynamic answers). +// +// For specifics, answer groups are selected by matching an answer to one or more 'rules' in the +// answer group (defined via a 'RuleSpec'). Rules represent inputs to predefined classifiers that +// can be used to match an answer. +// +// Interactions may also show hints to the learner if they get stuck and, after a certain number of +// hints, may offer to show the solution to the interaction. Not all interactions support hints and +// solutions. +// +// Specific interaction messages below more explicitly define what they support, and the types of +// answers that they expect. +// +// Finally, interactions may have 'customization arguments' which are creator-provided options to +// specialize the interaction for that particular context (such as tweaking hint or placeholder text +// for input boxes). message InteractionInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The different types of interactions. + // The type of the interaction. oneof interaction_type { + // An interaction that takes the form of a simple 'Continue' button. + ContinueInstance continue_instance = 1; - // The interaction that takes the form of a simple Continue button. - ContinueInstance continue = 1; - - // The interaction for fraction input. + // An interaction for inputting fractions. FractionInputInstance fraction_input = 2; - // The interaction for item selection input. + // An interaction for selecting one or more items from a list. ItemSelectionInputInstance item_selection_input = 3; - // The interaction for multiple item selection input. + // An interaction for selecting a single option among multiple presented choices. MultipleChoiceInputInstance multiple_choice_input = 4; - // The interaction for number input. + // An interaction for inputting numbers. NumericInputInstance numeric_input = 5; - // The interaction for text input. + // An interaction for inputting a line of text. TextInputInstance text_input = 6; - // The interaction for drag and drop sorting. + // An interaction for rearranging a list of items by dragging & dropping them. DragAndDropSortInputInstance drag_and_drop_sort_input = 7; - // The interaction allowing multiple-choice selection on an image. + // An interaction for selecting a learner-identified part of an image. ImageClickInputInstance image_click_input = 8; - // The interaction for ration input. + // An interaction for inputting ratios. RatioExpressionInputInstance ratio_expression_input = 9; - // The interaction that allows the exploration to end. + // An interaction that represents the end of an exploration and takes no direct user input other + // than navigating away from the exploration. This is not used in question play sessions. EndExplorationInstance end_exploration = 10; } } -// Answer type: none (N/A since no answers are submitted for this interaction). Structure of the -// continue instance. +// Represents an interaction where the user is presented with a simple 'Continue' button. Details: +// - Answer type: none (N/A since no answers are submitted for this interaction) +// - Has a default outcome: yes (it's actually the only outcome) +// - Has support for showing hints: no +// - Has support for showing a solution: no message ContinueInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // The default outcome of the continue instance. + // The default outcome for this interaction. Outcome default_outcome = 2; // Continue interactions cannot have custom answer groups, and do not support solutions. Users // cannot receive hints since only one answer is possible (clicking the button). - // Structure of the customization args of continue instance. + // Represents the customization arguments available for instances of the continue interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Note that while the continue interaction has a default button text defined, it's not used in - // the app since the default string needs to come through the app's strings so that it can be - // translated. - SubtitledHtml button_text = 1; + // Custom text to use for the 'Continue' button displayed for this interaction rather than using + // the button's default text ('Continue'). + SubtitledText button_text = 1; } } -// Answer type: Fraction. Structure of the fraction input interaction. +// Represents an interaction where the user is expected to input a textual fraction. Details: +// - Answer type: Fraction +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message FractionInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the fraction input. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the fraction input. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the fraction input. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of hints in the fraction input. + // The hints corresponding to this interaction. repeated Hint hints = 4; - // The solution of the fraction input. + // The solution corresponding to this interaction. Solution solution = 5; - // Structure of the customization args of the fraction input. + // Represents the customization arguments available for instances of the fraction input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The fraction is in simplest form or not. + // Specifics whether fractions must be provided in simplest form (that is, '2/4' would not be + // allowed, but '1/2' would be). bool requires_simplest_form = 1; - // The fraction allow to be in improper fraction. + // Specifics whether to allow improper fractions (i.e. whether fractions like '5/4' would be + // allowed). bool allow_improper_fractions = 2; - // The fraction contains non zero integer part or not. + // Specifics whether the fraction input can contain an integer part, that is, whether it can be + // a mixed fraction like '1 2/3'. bool allow_nonzero_integer_part = 3; - // The custom placeholders for fraction input. - SubtitledHtml custom_placeholder = 4; + // Specifies the placeholder/hint text that should be shown in the fraction input box prior to + // the user starting to enter an answer. Note that this will override the client's default text. + SubtitledText placeholder = 4; } - // Structure of the solution of the fraction input. + // Represents the specific solution available to instances of the fraction input interaction. message Solution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the solution in all interactions. + // The base properties of the solution. BaseSolution base_solution = 1; - // The correct answer of this fraction input. + // The correct answer for this interaction that should be shown to the user. Fraction correct_answer = 2; } - // Structure of the answer group of the fraction input. + // Represents the specific answer group used by instances of the fraction input interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the fraction input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rule spec of the fraction input. + // Represents specific rule specs used by instances of the fraction input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different rules which can be applied on the fraction input. + // Possible rule types for fraction answers. oneof rule_type { - - // A rule to check the fraction is equal to the fraction input. + // See the specific message's documentation for details on this rule type. IsExactlyEqualToSpec is_exactly_equal_to = 1; - // A rule to check the fraction is equivalent to the fraction input. + // See the specific message's documentation for details on this rule type. IsEquivalentToSpec is_equivalent_to = 2; - // A rule to check the fraction is equivalent and in the simplest form to the fraction input. + // See the specific message's documentation for details on this rule type. IsEquivalentToAndInSimplestFormSpec is_equivalent_to_and_in_simplest_form = 3; - // A rule to check the fraction is less than the fraction input. + // See the specific message's documentation for details on this rule type. IsLessThanSpec is_less_than = 4; - // A rule to check the fraction is greater than the fraction input. + // See the specific message's documentation for details on this rule type. IsGreaterThanSpec is_greater_than = 5; - // A rule to check the numerator of fraction is equal to the fraction input. + // See the specific message's documentation for details on this rule type. HasNumeratorEqualToSpec has_numerator_equal_to = 6; - // A rule to check the denominator of fraction is equal to the fraction input. + // See the specific message's documentation for details on this rule type. HasDenominatorEqualToSpec has_denominator_equal_to = 7; - // A rule to check the integer of fraction is equal to the fraction input. + // See the specific message's documentation for details on this rule type. HasIntegerPartEqualToSpec has_integer_part_equal_to = 8; - // A rule to check fraction has no fractional part to the fraction input. + // See the specific message's documentation for details on this rule type. HasNoFractionalPartSpec has_no_fractional_part = 9; - // A rule to check fraction has no fractional part equal to the fraction input. + // See the specific message's documentation for details on this rule type. HasFractionalPartExactlyEqualToSpec has_fractional_part_exactly_equal_to = 10; } - // Structure of the exactly equal rule check. + // Represents a rule spec for checking whether an answer exactly matches a creator-specified + // fraction. message IsExactlyEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } - // Structure of the equivalent rule check. + // Represents a rule spec for checking whether an answer is equivalent to a creator-specified + // fraction (but not necessarily exactly the same). message IsEquivalentToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } - // Structure of the equivalent and simple form rule check. + // Represents a rule spec for checking whether an answer is equivalent to a creator-specified + // fraction, in a similar way to IsEquivalentToSpec, except this also requires that the user's + // answer is in simplest form. message IsEquivalentToAndInSimplestFormSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } - // Structure of the less than rule check. + // Represents a rule spec for checking whether an answer is mathematically less than a + // creator-specified fraction. message IsLessThanSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } - // Structure of the greater than rule check. + // Represents a rule spec for checking whether an answer is mathematically greater than a + // creator-specified fraction. message IsGreaterThanSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } - // Structure of the numerator equality rule check. + // Represents a rule spec for checking whether an answer has a numerator equal to a + // creator-specified numerator. message HasNumeratorEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified numerator to match against the user's answer. int32 input = 1; } - // Structure of the denominator equality rule check. + // Represents a rule spec for checking whether an answer has a denominator equal to a + // creator-specified denominator. message HasDenominatorEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified denominator to match against the user's answer. uint32 input = 1; } - // Structure of the integer part rule check. + // Represents a rule spec for checking whether an answer has an integer part equal to a + // creator-specified integer part. message HasIntegerPartEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified integer part to match against the user's answer. int32 input = 1; } - // Structure of the no fraction input rule check. + // Represents a rule spec for checking whether an answer is missing its fractional part (i.e. + // that it's just a whole number). message HasNoFractionalPartSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // No inputs for this rule spec. } - // Structure of the fraction part exactly equality rule check. + // Represents a rule spec for checking whether an answer has a fractional part exactly equal to + // a creator-specified fraction (whose integer part is ignored during classification). message HasFractionalPartExactlyEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified fraction to match against the user's answer. Fraction input = 1; } } } -// Answer type: SetOfTranslatableHtmlContentIds. Structure of the item selection input interaction. +// Represents an interaction where the user can select one or more options from a list of choices. +// Details: +// - Answer type: SetOfTranslatableHtmlContentIds +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: no message ItemSelectionInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the item selection input. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the item selection input. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the item selection input. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of hints in the item selection input. + // The hints corresponding to this interaction. repeated Hint hints = 4; // Item selection does not support solutions. - // Structure of the customization args of the item selection input. + // Represents the customization arguments available for instances of the item selection input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The minimum number of items allowed for selection. - int32 min_allowable_selection_count = 1; + // Specifies the minimum number of items that must be selected before an answer can be + // submitted. + uint32 min_allowable_selection_count = 1; - // The maximum number of items allowed for selection. - int32 max_allowable_selection_count = 2; + // Specifies the maximum number of items that may be selected. If this '1' then the options will + // be displayed as radio buttons instead of checkboxes. + uint32 max_allowable_selection_count = 2; // The list of selectable items. - repeated SubtitledHtml choices = 3; + repeated SubtitledText choices = 3; } - // Structure of a single answer group of item selection input. + // Represents the specific answer group used by instances of the item selection input interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the item selection input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the item selection input. + // Represents specific rule specs used by instances of the item selection input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different type of rules for the item selection input instance. + // Possible rule types for item selection answers. oneof rule_type { - - // A rule to check the equality. + // See the specific message's documentation for details on this rule type. EqualsSpec equals = 1; - // A rule to check atleast one item selected. + // See the specific message's documentation for details on this rule type. ContainsAtLeastOneOfSpec contains_at_least_one_of = 2; - // A rule to check non of the item is selected. + // See the specific message's documentation for details on this rule type. DoesNotContainAtLeastOneOfSpec does_not_contain_at_least_one_of = 3; - // A rule to check the propoer subset. + // See the specific message's documentation for details on this rule type. IsProperSubsetOfSpec is_proper_subset_of = 4; } - // Structure of the equal rule check. + // Represents a rule spec for checking whether an answer has exactly the same items as a + // creator-specified list of item selections. Note that order does not matter for these items. message EqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified list of item selections to match against the user's + // answer. SetOfTranslatableHtmlContentIds input = 1; } - // Structure of atleast one item selection rule check. + // Represents a rule spec for checking whether an answer has at least one of the items defined + // in a creator-specified list of item selections. Note that order does not matter for these + // items. message ContainsAtLeastOneOfSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified list of item selections to match against the user's + // answer. SetOfTranslatableHtmlContentIds input = 1; } - // Structure of non of the item selection rule check. + // Represents a rule spec for checking whether an answer has none of the items defined in a + // creator-specified list of item selections. Note that order does not matter for these items. message DoesNotContainAtLeastOneOfSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified list of item selections to match against the user's + // answer. SetOfTranslatableHtmlContentIds input = 1; } - // Structure of proper subset of item selection rule check. + // Represents a rule spec for checking whether an answer is a proper subset of a + // creator-specified list of item selections (treated as a set), that is, that it's fully + // contained in the creator-specified set but is not exactly equal to it. message IsProperSubsetOfSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified list of item selections to match against the user's + // answer. SetOfTranslatableHtmlContentIds input = 1; } } } -// Answer type: non-negative int (uint32). Structure of the multiple choice input interaction. +// Represents an interaction where the user can select one choice among a list of choices. Details: +// - Answer type: non-negative int (protobuf type: uint32) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: no message MultipleChoiceInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the multiple choice input. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the multiple choice input. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the multiple choice input. + // The default outcome for this interaction. Outcome default_outcome = 3; - // The list of hints for this multiple choice input. + // The hints corresponding to this interaction. repeated Hint hints = 4; // Multiple choice does not support solutions. - // Structure of the customization args of the multiple choice input. + // Represents the customization arguments available for instances of the multiple choice input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A list of possible choices from the multiple items. - repeated SubtitledHtml choices = 1; + // The list of selectable items. + repeated SubtitledText choices = 1; } - // Structure of a single answer group of multiple choice input. + // Represents the specific answer group used by instances of the multiple choice input + // interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A base answer group is a set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the multiple choice input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the multiple choice input. + // Represents specific rule specs used by instances of the multiple choice input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Differnt type of rules for the multiple choice input. + // Possible rule types for multiple choice answers. oneof rule_type { - - // A rule to check the equality. + // See the specific message's documentation for details on this rule type. EqualsSpec equals = 1; } - // Structure of the equal rule check. + // Represents a rule spec for checking whether an answer matches to a creator-specified multiple + // choice option index. message EqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified multiple choice option index to match against the + // user's answer. uint32 input = 1; } } } -// Answer type: real (double). Structure of the number input interaction. +// Represents an interaction where the user can input an numeric-only answer. Details: +// - Answer type: real number (protobuf type: uint32) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message NumericInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A list of answer groups of the numeric input. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 1; - Solution solution = 2; - // The default outcome of the numeric input. - Outcome default_outcome = 3; - repeated Hint hints = 4; + // The default outcome for this interaction. + Outcome default_outcome = 2; + + // The hints corresponding to this interaction. + repeated Hint hints = 3; + + // The solution corresponding to this interaction. + Solution solution = 4; // Numeric input does not have any customization arguments. - // Structure of the solution of the numeric input. + // Represents the specific solution available to instances of the numeric input interaction. message Solution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the solution in all interactions. + // The base properties of the solution. BaseSolution base_solution = 1; - // The correct answer of this numeric input. + // The correct answer for this interaction that should be shown to the user. double correct_answer = 2; } - // Structure of a single answer group of numeric input. + // Represents the specific answer group used by instances of the numeric input interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the numeric input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the numeric input. + // Represents specific rule specs used by instances of the numeric input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different type of rules which can be applied on the numeric input. + // Possible rule types for numeric input answers. oneof rule_type { - - // A rule to check the equality. + // See the specific message's documentation for details on this rule type. EqualsSpec equals = 1; - // A rule to check less than a value or not. + // See the specific message's documentation for details on this rule type. IsLessThanSpec is_less_than = 2; - // A rule to check the greater than value or not. + // See the specific message's documentation for details on this rule type. IsGreaterThanSpec is_greater_than = 3; - // A rule to check the less than or equal value or not. + // See the specific message's documentation for details on this rule type. IsLessThanOrEqualToSpec is_less_than_or_equal_to = 4; - // A rule to check the greter than or equal value or not. + // See the specific message's documentation for details on this rule type. IsGreaterThanOrEqualToSpec is_greater_than_or_equal_to = 5; - // A rule to check the inclusive range. + // See the specific message's documentation for details on this rule type. IsInclusivelyBetweenSpec is_inclusively_between = 6; - // A rule to check the tolerance range. + // See the specific message's documentation for details on this rule type. IsWithinToleranceSpec is_within_tolerance = 7; } - // Structure of the equal rule check. + // Represents a rule spec for checking whether an answer exactly* equals a creator-specified real + // value. *Note that the match here uses an epsilon comparison to account for IEEE 754 floating + // point rounding errors. message EqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified real value to match against the user's answer. double input = 1; } - // Structure of the less than rule check. + // Represents a rule spec for checking whether an answer is numerically less than a + // creator-specified real value. message IsLessThanSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified real value to match against the user's answer. double input = 1; } - // Structure of the greater than rule check. + // Represents a rule spec for checking whether an answer is numerically greater than a + // creator-specified real value. message IsGreaterThanSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified real value to match against the user's answer. double input = 1; } - // Structure of the less than or equal rule check. + // Represents a rule spec for checking whether an answer is numerically less than or exactly + // equal to a creator-specified real value. message IsLessThanOrEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified real value to match against the user's answer. double input = 1; } - // Structure of the greater than or equal rule check. + // Represents a rule spec for checking whether an answer is numerically greater than or exactly + // equal to a creator-specified real value. message IsGreaterThanOrEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified real value to match against the user's answer. double input = 1; } - // Structure of the inclusive range rule check. + // Represents a rule spec for checking whether an answer is within a creator-specified fully + // closed/inclusive range. message IsInclusivelyBetweenSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // lower value in inclusive range. + // Corresponds to the creator-specified inclusive lower bound for comparison against the + // user's answer. double inputLowerInclusive = 1; - // upper value in inclusive range. + // Corresponds to the creator-specified inclusive upper bound for comparison against the + // user's answer. double inputUpperInclusive = 2; } - // Structure of the tolerance ranage rule check. + // Represents a rule spec for checking whether an answer is equal to a creator-specified value + // when accounting for a creator-specific tolerance range. message IsWithinToleranceSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Input tolerance value. + // Corresponds to the creator-specified tolerance to consider when matching against the user's + // answer. double inputTolerance = 1; - // Tolerance value to compare. + // Corresponds to the creator-specified value to compare against the user's answer. double inputComparedValue = 2; } } } -// Answer type: normalized string (string). Structure of the text input interaction. +// Represents an interaction where the user can input a line of text. Details: +// - Answer type: normalized string (protobuf type: string) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes +// +// Note that all answers submitted to this interaction undergo 'string normalization' which involves +// trimming leading & trailing whitespace, removing all non-space whitespace, and replacing extra +// spaces such that at most one space separates characters. message TextInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the text input instance. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the text input interaction instance. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the text instance. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of hints for text input instance. + // The hints corresponding to this interaction. repeated Hint hints = 4; - // The solution of the text input instance. + // The solution corresponding to this interaction. Solution solution = 5; - // Structure of the customization args of the text input instance. + // Represents the customization arguments available for instances of the text input interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A placeholder value for the text input instance. - SubtitledHtml placeholder = 1; + // Specifies the placeholder/hint text that should be shown in the text input box prior to the + // user starting to enter an answer. Note that this will override the client's default text. + SubtitledText placeholder = 1; - // The number of rows for the text input instance. - int32 rows = 2; + // Specifies the number of rows (visual lines) that should be allowed for text input. + uint32 rows = 2; } - // Structure of the solution of the text input instance. + // Represents the specific solution available to instances of the text input interaction. message Solution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the solution in all interactions. + // The base properties of the solution. BaseSolution base_solution = 1; - // The correct answer of this text instance. + // The correct answer for this interaction that should be shown to the user. string correct_answer = 2; } - // Structure of a single answer group of text input. + // Represents the specific answer group used by instances of the text input interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the text instance. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the text input instance. + // Represents specific rule specs used by instances of the text input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different rules which can be applied on the text input instance. + // Possible rule types for text input answers. oneof rule_type { - - // A rule to check equal text. + // See the specific message's documentation for details on this rule type. EqualsSpec equals = 1; - // A rule to check starting text of input. + // See the specific message's documentation for details on this rule type. StartsWithSpec starts_with = 2; - // A rule to check a substring of the input text. + // See the specific message's documentation for details on this rule type. ContainsSpec contains = 3; - // A rule to check the input text equals. + // See the specific message's documentation for details on this rule type. FuzzyEqualsSpec fuzzy_equals = 4; } - // Structure of the equal rule check. + // Represents a rule spec for checking whether an answer is exactly equal to (after string + // normalization) to any of the strings in a creator-specified string list. message EqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified set of text input values to match against the user's + // answer. TranslatableSetOfNormalizedString input = 1; } - // Structure of the rule to check starting text. + // Represents a rule spec for checking whether an answer starts with any of the strings in a + // creator-specified string list (with string normalization). message StartsWithSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified set of text input values to match against the user's + // answer. TranslatableSetOfNormalizedString input = 1; } - // Structureof the rule to check the substring of the text. + // Represents a rule spec for checking whether an answer contains any of the strings in a + // creator-specified string list (with string normalization). message ContainsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified set of text input values to match against the user's + // answer. TranslatableSetOfNormalizedString input = 1; } - // Structure of the rule to check text equality. + // Represents a rule spec for checking whether an answer fuzzily equals any of the strings in a + // creator-specified string list (with string normalization), that is, whether it equals one of + // the strings with at most one character misspelled. message FuzzyEqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified set of text input values to match against the user's + // answer. TranslatableSetOfNormalizedString input = 1; } } } -// Answer type: ListOfSetsOfTranslatableHtmlContentIds. Structure of the drag and drop sort input -// interaction. +// Represents an interaction where the user can rearrange a list of options using drag & drop +// functionality. Details: +// - Answer type: ListOfSetsOfTranslatableHtmlContentIds +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message DragAndDropSortInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the drag and drop sort instance. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the drag and drop sort input interaction instance. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the drag and drop sort instance. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of all the hints for drag and drop sort instance. + // The hints corresponding to this interaction. repeated Hint hints = 4; - // The solution of the drag and drop sort instance. + // The solution corresponding to this interaction. Solution solution = 5; - // Structure of the customization args of the drag and drop sort instance. + // Represents the customization arguments available for instances of the drag and drop sort input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A list of choice for drag and drop. - repeated SubtitledHtml choices = 1; + // The list of items that can be dragged & dropped. + repeated SubtitledText choices = 1; - // Items are allowed at same position or not. + // Specifies whether items can be allowed at the same position in the list (i.e. linked or + // unlinked). bool allowMultipleItemsInSamePosition = 2; } - // Structure of the solution of the drag and drop sort instance. + // Represents the specific solution available to instances of the drag and drop sort input + // interaction. message Solution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the solution in all interactions. + // The base properties of the solution. BaseSolution base_solution = 1; - // The correct answer of this drag and drop sort instance. + // The correct answer for this interaction that should be shown to the user. ListOfSetsOfTranslatableHtmlContentIds correct_answer = 2; } - // Structure of a single answer group of drag and drop sort input. + // Represents the specific answer group used by instances of the drag and drop sort input + // interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the drag and drop sort instance. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the drag and drop sort instance. + // Represents specific rule specs used by instances of the drag and drop sort input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different rules which can be applied on the drag and drop sort instance. + // Possible rule types for drag and drop answers. oneof rule_type { - - // A rule to check equal order. + // See the specific message's documentation for details on this rule type. IsEqualToOrderingSpec is_equal_to_ordering = 1; - // A rule to check equal order and one item at incorrect position. + // See the specific message's documentation for details on this rule type. IsEqualToOrderingWithOneItemAtIncorrectPositionSpec is_equal_to_ordering_with_one_item_at_incorrect_position = 2; - // A rule to check the position of an item. + // See the specific message's documentation for details on this rule type. HasElementXAtPositionYSpec has_element_x_at_position_y = 3; - // A rule to check the previous position of an item. + // See the specific message's documentation for details on this rule type. HasElementXBeforeElementYSpec has_element_x_before_element_y = 4; } - // Structure of an equal order rule. + // Represents a rule spec for checking whether an answer exactly matches a creator-specified + // drag and drop configuration (that is, a list of drag and drop items with some items + // potentially on the same line), with ordering being considered. message IsEqualToOrderingSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified drag and drop configuration to match against the + // user's answer. ListOfSetsOfTranslatableHtmlContentIds input = 1; } - // Structure of an equal order with one incorrect position rule. + // Represents a rule spec for checking whether an answer exactly matches a creator-specified + // drag and drop configuration (that is, a list of drag and drop items with some items + // potentially on the same line), with ordering being considered and with exactly one item being + // in the incorrect position. message IsEqualToOrderingWithOneItemAtIncorrectPositionSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified drag and drop configuration to match against the + // user's answer. ListOfSetsOfTranslatableHtmlContentIds input = 1; } - // Structure of an item position check rule. + // Represents a rule spec for checking whether an answer has an element at a creator-specified + // position exactly matched a creator-specified option (which should correspond to one of the + // options defined in the interaction's customization arguments). message HasElementXAtPositionYSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The item whose position to check. + // Corresponds to the creator-specified single element to match against the user's answer. TranslatableHtmlContentId element = 1; - // The position of the item to check. + // Corresponds to the creator-specified element index with which to extract from the user's + // answer a value to compare against the defined element. uint32 position = 2; } - // Structure of an item previous position check rule. + // Represents a rule spec for checking whether an answer has two creator-specified elements such + // that one of the particular elements occurs before another one of the specified elements, + // where both elements should correspond to options defined in the interaction's customization + // arguments). message HasElementXBeforeElementYSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The previous position of an item. + // Corresponds to the creator-specified element that's expected to be contained in the user's + // answer. TranslatableHtmlContentId considered_element = 1; - // The next element of the item. + // Corresponds to the creator-specified element that's expected to be contained in the user's + // answer. TranslatableHtmlContentId later_element = 2; } } } -// Answer type: ClickOnImage. Structure of the image selection input interaction. +// Represents an interaction where the user can select a region of an image. Details: +// - Answer type: ClickOnImage +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: no message ImageClickInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the image click input. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the image click input. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the image click input. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of all the hints for image click input. + // The hints corresponding to this interaction. repeated Hint hints = 4; // Image click input doesn't yet support solutions. - // Structure of the customization args of the image click input. + // Represents the customization arguments available for instances of the image click input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // An image with the regions. + // Defines the image to display to the user, and all of the constituent regions that the user + // may selected. ImageWithRegions image_and_regions = 1; } - // Structure of a single answer group of image selection input. + // Represents the specific answer group used by instances of the image click input interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A base answer group is a set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the image click input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the image click input. + // Represents specific rule specs used by instances of the image click input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different rules which can be applied on the image click input. + // Possible rule types for image click answers. oneof rule_type { - - // A rule to check the region availability. + // See the specific message's documentation for details on this rule type. IsInRegionSpec is_in_region = 1; } - // Structure of a single is in region. + // Represents a rule spec for checking whether an answer corresponds to a creator-specified + // region (as a determination of that region being clicked by the user). message IsInRegionSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified image region label to match against the user's answer. string input_region = 1; } } } -// Answer type: RatioExpression. Structure of the ratio input interaction. +// Represents an interaction where the user can input the ratio between two integers. Details: +// - Answer type: RatioExpression +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message RatioExpressionInputInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of arguments to customize the ratio expression input. + // The customization arguments for this interaction. CustomizationArgs customization_args = 1; - // A list of answer groups of the ratio expression input interaction instance. + // The answer groups for this interaction. repeated AnswerGroup answer_groups = 2; - // The default outcome of the ratio expression input. + // The default outcome for this interaction. Outcome default_outcome = 3; - // A list of hints for the ratio expression input. + // The hints corresponding to this interaction. repeated Hint hints = 4; - // The solution of the ratio expression input. + // The solution corresponding to this interaction. Solution solution = 5; - // Structure of the customization args of the ratio expression input. + // Represents the customization arguments available for instances of the ratio expression input + // interaction. message CustomizationArgs { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A placeholder for the ratio expression input. - SubtitledHtml placeholder = 1; + // Specifies the placeholder/hint text that should be shown in the ratio input box prior to the + // user starting to enter an answer. Note that this will override the client's default text. + SubtitledText placeholder = 1; - // The number of terms in the ration expression. - int32 number_of_terms = 2; + // The number of elements that the answer must have, or 0 to indicate that a ratio of any length + // will be accepted. For example, if this is set to '5' then the ratio must have 5 components + // (such as 1:2:3:4:5). + uint32 number_of_terms = 2; } - // Structure of the solution of the ratio expression input. + // Represents the specific solution available to instances of the ratio expression input + // interaction. message Solution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the solution in all interactions. + // The base properties of the solution. BaseSolution base_solution = 1; - // The correct answer of this ratio expression input. + // The correct answer for this interaction that should be shown to the user. RatioExpression correct_answer = 2; } - // Structure of a single answer group of ratio expression input. + // Represents the specific answer group used by instances of the ratio expression input + // interaction. message AnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // A set of common items for the answer groups in all the interactions. + // The base properties of the answer group. BaseAnswerGroup base_answer_group = 1; - // A list of all the rules of the ratio expression input. + // The list of all rules to match for this answer group. repeated RuleSpec rule_specs = 2; } - // Structure of the rules of the ratio expression input. + // Represents specific rule specs used by instances of the ratio expression input interaction. message RuleSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // Different rules which can be applied on the ratio expression input. + // Possible rule types for ratio expression answers. oneof rule_type { - - // A rule to check the equality. + // See the specific message's documentation for details on this rule type. EqualsSpec equals = 1; - // A rule to check the equivalent. + // See the specific message's documentation for details on this rule type. IsEquivalentSpec is_equivalent = 2; - // A rule to check the number of terms. + // See the specific message's documentation for details on this rule type. HasNumberOfTermsEqualToSpec has_number_of_terms_equal_to = 3; - // A rule to check whether a ratio has a specific term with a specific value. + // See the specific message's documentation for details on this rule type. HasSpecificTermEqualToSpec has_specific_term_equal_to = 4; } - // Structure of the equal rule check. + // Represents a rule spec for checking whether an answer exactly equals a creator-specified + // ratio expression. message EqualsSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified ratio expression to match against the user's answer. RatioExpression input = 1; } - // Structure of the equivalent rule check. + // Represents a rule spec for checking whether an answer is equivalent to a creator-specified + // ratio expression (e.g. '1:2' amd '2:4' would be considered equivalent, but not equal). message IsEquivalentSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified ratio expression to match against the user's answer. RatioExpression input = 1; } - // Structure of the number of terms equal rule check. + // Represents a rule spec for checking whether an answer has a creator-specified number of + // terms. message HasNumberOfTermsEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified number of terms to match against the user's answer. uint32 input_term_count = 1; } - // Structure of the specific terms rule check. + // Represents a rule spec for checking whether an answer has a creator-specified term value at a + // creator-specified term position within the answer. message HasSpecificTermEqualToSpec { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // Corresponds to the creator-specified term index to match against the user's answer. uint32 input_term_index = 1; + + // Corresponds to the creator-specified expected term value to match against the user's + // answer. uint32 input_expected_term_value = 2; } } } -// Answer type: none (N/A since no answers are submitted for this interaction). Structure of a -// single end exploration type interaction. +// Represents an interaction where the user has reached the end of the exploration, and has the +// choice to navigate away from it. Details: +// - Answer type: none (N/A since no answers are submitted for this interaction) +// - Has a default outcome: no (N/A since there's no state routing after this state; it's terminal) +// - Has support for showing hints: no +// - Has support for showing a solution: no message EndExplorationInstance { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -919,81 +1109,62 @@ message EndExplorationInstance { // interactions. No hints can be shown to the user. } -// Common fields for all answer groups. +// Represents the base structure for an answer group (that is, the group of fields common among all +// interaction answer groups). message BaseAnswerGroup { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // An outcome is a common way of reponse for all interactions. + // The outcome details for how the platform should response to an answer matched to this group. Outcome outcome = 1; - // The misconception which is tagged to a single skill. + // The misconception (if any) associated with answers matched to this group. Misconception tagged_skill_misconception = 2; } -// Structure of the outcome of any interaction. +// Represents the response the platform should provide for a particular answer. message Outcome { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The name of the next state. + // The name of the state to which the user should next be navigated (which may be the same as the + // current state if the learner should try a different answer). string destination_state = 1; - // The feedback is the reponse for the learners input in interaction. - SubtitledHtml feedback = 2; + // The textual feedback, if any, to show the user based on their response. + SubtitledText feedback = 2; - // The label to mark the answer correct. + // Whether the answer matched to this outcome should be considered 'correct' (which may lead to + // different platform behavior, such as showing a 'correct' banner). Note that some correct + // answers may not be labelled as correct, so this being false or absent does not necessarily + // indicate an answer is wrong. bool labelled_as_correct = 3; } -// Structure for a single hint +// Represents a hint that may be shown to the learner to help them get unstuck (in cases when the +// platform detects that the learner may be having difficulty proceeding in a lesson or training +// session). message Hint { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The content of the hint. - SubtitledHtml hint_content = 1; + // The main content of the hint to show the user. + SubtitledText hint_content = 1; } -// Common fields for all solutions. +// Represents the base structure for a solution (that is, the group of fields common among all +// interaction solutions). message BaseSolution { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The explanation of the solution. - SubtitledHtml explanation = 1; -} - -// Convenience collection object for all potential types of solutions. -message Solution { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - // The different type of interactions existed in an exploration. - oneof interaction_type { - - // The interaction to allow fraction inputs. - FractionInputInstance.Solution fraction_instance_solution = 1; - - // The interaction to allow numeric inputs. - NumericInputInstance.Solution numeric_input_instance_solution = 2; - - // The interaction to allow text inputs. - TextInputInstance.Solution text_input_instance_solution = 3; - - // The interaction to allow drag and drop inputs. - DragAndDropSortInputInstance.Solution drag_and_drop_sort_input_instance_solution = 4; - - // The interaction to allow ratio inputs. - RatioExpressionInputInstance.Solution ratio_expression_input_instance_solution = 5; - } + // The explanation of the solution to show the user. + SubtitledText explanation = 1; } -// Structure for a single misconception, after parsing the original string received from the -// backend: -// https://github.com/oppia/oppia/blob/896466ae8b/core/templates/pages/exploration-editor-page/ -// editor-tab/templates/modal-templates/add-answer-group-modal.controller.ts#L60 +// Represents a single misconception of a particular skill. message Misconception { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - // The id of the skill. + // The ID of the skill that the user is likely misunderstanding. string skill_id = 1; - // The id of the misconception. + // The ID of the misconception (for cataloging purposes, such as during training sessions). string misconception_id = 2; } diff --git a/proto/v1/structure/topic_summary.proto b/proto/v1/structure/topic_summary.proto index c7465b6..cb0baa9 100644 --- a/proto/v1/structure/topic_summary.proto +++ b/proto/v1/structure/topic_summary.proto @@ -8,101 +8,114 @@ import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// Structure for a single topic summary. -message TopicSummary { +// Represents the summary of a topic that is available to the user to download. A topic is a fully +// contained module of lessons, explanations, and practice questions to learn a specific subcategory +// of a subject area (such as 'place values' or 'fractions'). +// +// Topics organize lessons into stories which organize teaching around a plot to help contextualize +// the lessons and to make them more engaging to learners. +// +// Topics organize 'skills' (i.e. granular units of learning) into groups called 'subtopics' which +// have corresponding revision cards that learners may use to get a high-level refresher of the +// corresponding skills. +message DownloadableTopicSummary { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; + // The version defining the internal structure of this message. org.oppia.proto.v1.versions.TopicSummaryProtoVersion proto_version = 1; - // The id of the topic. + // The ID of the topic. string id = 2; - // The name of the topic. + // The human-readable name of the topic. This is expected to be in English. string name = 3; - // The description of the topic. + // The human-readable description of the topic. This is expected to be in English. string description = 4; - // A list of story summaries related to this TopicSummary. + // The list of stories available to play in the topic corresponding to this sumamry. repeated StorySummary story_summaries = 5; - // A list of all subtopics corresponding to this topic. + // The list of subtopics available in the topic corresponding to this sumamry. repeated SubtopicSummary subtopic_summaries = 6; // The thumbnail image corresponding to this topic. - Thumbnail thumbnail = 7; // TODO - - // Whether the corresponding topic has been published. - bool is_published = 8; + Thumbnail thumbnail = 7; // The version of this topic's contents. - int32 content_version = 9; + uint32 content_version = 8; } -// Structure of a single story summary. +// Represents the summary of a story that can be played within a particular topic. Stories aim to +// teach all of the skills covered by a topic (as defined by the topic's subtopics) via a linear +// pathway of 'chapters' (which correspond to explorations). message StorySummary { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; - // The id of the story. + // The ID of the story. string id = 1; - // The title of the story. + // The human-readable title of the story. This is expected to be in English. string title = 2; - // The description of the story. + // The human-readable description of the story. This is expected to be in English. string description = 3; // The thumbnail image of the story. - Thumbnail thumbnail = 4; // TODO + Thumbnail thumbnail = 4; // The summaries of all chapters in this story. repeated ChapterSummary chapters = 5; // The version of this story's contents. - int32 content_version = 6; + uint32 content_version = 6; } -// Structure of a single chapter summary. +// Represents the summary of a single chapter within a story of a topic. Each chapter corresponds to +// a single exploration (see Exploration's documentation for more details). message ChapterSummary { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The thumbnail image for this chapter. - Thumbnail thumbnail = 1; // TODO + Thumbnail thumbnail = 1; - // The title of the chapter. + // The human-radable title of the chapter. This is expected to be in English, and is expected to + // exactly match the title of the exploration associated to this chapter. string title = 2; - // The id of the exploration to which this ChapterSummary is associated. + // The ID of the exploration to which this ChapterSummary is associated. string exploration_id = 3; - // The version of this chapter's contents. - int32 content_version = 4; + // The version of this chapter's contents. This is expected to always match the exploration + // associated to this chapter. + uint32 content_version = 4; } -// Structure of a single subtopic summary. +// Represents the summary of a subtopic (that is, a group of skills logically organized within a +// topic). message SubtopicSummary { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The index of the subtopic (within its correspnoding topic). - int32 index = 1; + uint32 index = 1; - // All the skills in this subtopic. + // The list of all skills grouped by this subtopic. repeated SkillSummary skill_summaries = 2; // The version of this subtopic's contents. - int32 content_version = 3; + uint32 content_version = 3; } -// Structure of a single skill summary. +// Represents the summary of a skill (see DownloadableTopicSummary for context on skills). message SkillSummary { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; - // The id of the skill. + // The ID of the skill. string id = 1; - // The name of the skill. + // The human-readable name of the skill. This is expected to be in English. string name = 2; // The version of this skill's contents. - int32 content_version = 3; + uint32 content_version = 3; } diff --git a/proto/v1/versions/BUILD.bazel b/proto/v1/versions/BUILD.bazel index f25150b..102377e 100644 --- a/proto/v1/versions/BUILD.bazel +++ b/proto/v1/versions/BUILD.bazel @@ -1,5 +1,6 @@ """ -TODO +Libraries that define proto versions used by API & structural protos for client-server +compatibility. """ load("@rules_proto//proto:defs.bzl", "proto_library") diff --git a/proto/v1/versions/api_versions.proto b/proto/v1/versions/api_versions.proto index c501654..e10c154 100644 --- a/proto/v1/versions/api_versions.proto +++ b/proto/v1/versions/api_versions.proto @@ -15,23 +15,41 @@ extend google.protobuf.MessageOptions { ApiProtoVersionType api_proto_version_type = 2000; } -// The only currently-supported proto version for the TopicListRequestResponse. +// Represents the version of the proto structures for topic list request & response messages. This +// structure is never expected to change. +// +// See the README for details on how these versions are meant to be used. message TopicListRequestResponseProtoVersion { option (api_proto_version_type) = UNVERSIONED_API_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The only currently-supported proto version for the TopicContentRequestResponse. +// Represents the version of the proto structures for topic content request & response messages. +// This structure is never expected to change. +// +// See the README for details on how these versions are meant to be used. message TopicContentRequestResponseProtoVersion { option (api_proto_version_type) = UNVERSIONED_API_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } +// Represents the type of versioning corresponding to an API proto message. enum ApiProtoVersionType { + // The default version type (that is, unspecified and not corresponding to any versioning scheme). + // This generally should not be used. API_PROTO_VERSION_TYPES_UNSPECIFIED = 0; + + // Indicates that the proto is not bound by a version, and thus extreme care must be taken in + // changing its structure. UNVERSIONED_API_PROTO = 1; + + // Indicates that the proto is bound by TopicListRequestResponseProtoVersion. TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION = 2; + + // Indicates that the proto is bound by TopicContentRequestResponseProtoVersion. TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION = 3; } diff --git a/proto/v1/versions/structure_versions.proto b/proto/v1/versions/structure_versions.proto index 73865d7..42e1e2c 100644 --- a/proto/v1/versions/structure_versions.proto +++ b/proto/v1/versions/structure_versions.proto @@ -14,73 +14,138 @@ extend google.protobuf.MessageOptions { // Defines the version type corresponding to a structure proto. StructureProtoVersionType structure_proto_version_type = 1000; } +extend google.protobuf.EnumOptions { + // Defines the version type corresponding to a structure enum. + StructureProtoVersionType structure_enum_version_type = 1001; +} -// The version of the TopicSummary proto. +// Represents the version of the proto structures for topic summary messages. This structure is +// never expected to change. +// +// See the README for details on how these versions are meant to be used. message TopicSummaryProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the RevisionCard proto. +// Represents the version of the proto structures for revision card messages. This structure is +// never expected to change. +// +// See the README for details on how these versions are meant to be used. message RevisionCardProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the ConceptCard proto. +// Represents the version of the proto structures for concept card messages. This structure is never +// expected to change. +// +// See the README for details on how these versions are meant to be used. message ConceptCardProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the Exploration proto. +// Represents the version of the proto structures for explorations messages. This structure is never +// expected to change. +// +// See the README for details on how these versions are meant to be used. message ExplorationProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the Question proto. +// Represents the version of the proto structures for question messages. This structure is never +// expected to change. +// +// See the README for details on how these versions are meant to be used. message QuestionProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// This version implies interaction compatibility since interactions are tightly defined in the -// structures. The version of the State proto. +// Represents the version of the proto structures for state messages. +// This structure is never expected to change. +// +// Note that this version also implies compatibility among changes to interactions since +// interactions are defined using strong types, and all of those proto messages are bound to this +// version. +// +// See the README for details on how these versions are meant to be used. message StateProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the Language proto. +// Represents the proto version of multiple language-tied messages. Note that these are versioned +// separately from the structures that reference them since multiple topic substructures reference +// common messages (e.g. RecordedVoiceovers), so changes in the structures need to be properly +// shared across all use cases without necessarily updating the individual proto versions for each +// of those messages. Note also that this structrure is never expected to change. +// +// See also the README for details on how these versions are meant to be used. message LanguageProtosVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } -// The version of the Image proto. +// Represents the version of the proto structures for image messages. This structure is never +// expected to change. This also shares some characteristics with LanguageProtosVersion in that it's +// used to track versioning for highly centralized & shared structures. +// +// See the README for details on how these versions are meant to be used. message ImageProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; - int32 version = 1; + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; } +// Represents the type of versioning corresponding to a structure proto message. enum StructureProtoVersionType { + // The default version type (that is, unspecified and not corresponding to any versioning scheme). + // This generally should not be used. STRUCTURE_PROTO_VERSION_TYPES_UNSPECIFIED = 0; + + // Indicates that the proto is not bound by a version, and thus extreme care must be taken in + // changing its structure. UNVERSIONED_STRUCTURE_PROTO = 1; + + // Indicates that the proto is bound by TopicSummaryProtoVersion. TOPIC_SUMMARY_PROTO_VERSION = 2; + + // Indicates that the proto is bound by RevisionCardProtoVersion. REVISION_CARD_PROTO_VERSION = 3; + + // Indicates that the proto is bound by ConceptCardProtoVersion. CONCEPT_CARD_PROTO_VERSION = 4; + + // Indicates that the proto is bound by ExplorationProtoVersion. EXPLORATION_PROTO_VERSION = 5; + + // Indicates that the proto is bound by QuestionProtoVersion. QUESTION_PROTO_VERSION = 6; + + // Indicates that the proto is bound by StateProtoVersion. STATE_PROTO_VERSION = 7; + + // Indicates that the proto is bound by LanguageProtosVersion. LANGUAGE_PROTOS_VERSION = 8; + + // Indicates that the proto is bound by ImageProtoVersion. IMAGE_PROTO_VERSION = 9; } diff --git a/repo/BUILD b/repo/BUILD index d0f4e48..d3b683c 100644 --- a/repo/BUILD +++ b/repo/BUILD @@ -1,3 +1,5 @@ """ -TODO: fill in +Reusable Starlark macros for setting up both the local Bazel WORKSPACE, and also for preparing other +workspaces for importing the protos defined in this project. See the README for more details on +importing this repository in other Bazel workspaces. """ diff --git a/repo/deps.bzl b/repo/deps.bzl index 95ca680..e65d5a8 100644 --- a/repo/deps.bzl +++ b/repo/deps.bzl @@ -1,6 +1,9 @@ """ -TODO: document +Defines Starlark macros that are used to import the dependencies needed to build the Oppia proto API +project (such as for cases when another Bazel workspace depends on this project). See the importing +instructions in the README for more details. """ + load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") # Note to developers: Please keep this dict sorted by key to make it easier to find dependencies. @@ -60,8 +63,17 @@ def _setUpRulesJava(): _setUpHttpArchiveDependency(name = "rules_java") def initializeDepsForWorkspace(): - # TODO: docstring. Explain toolchain initializations that must be called may need to be called. + """ + Loads the dependencies needed to be able to build the Oppia proto API project. + + Note that this must be called after loading in this deps file, for example: + + load("//repo:deps.bzl", "initializeDepsForWorkspace") + initializeDepsForWorkspace() + Note also that toolchains may need to be set up after loading this dependencies (see + toolchains.bzl). + """ # Set up Python (as a prerequisite dependency for Protobuf). _setUpPython() diff --git a/repo/toolchains.bzl b/repo/toolchains.bzl index aeebd2d..0d818cf 100644 --- a/repo/toolchains.bzl +++ b/repo/toolchains.bzl @@ -1,12 +1,23 @@ """ -TODO: document +Defines Starlark macros that are used to set up dependency toolcahins needed to build the Oppia +proto API project (such as for cases when another Bazel workspace depends on this project). See the +importing instructions in the README for more details. """ load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") def initializeToolchainsForWorkspace(): - # TODO: docstring explaining the load()s that need to happen before this. Explain that this file also can't be loaded until after deps are set up. + """ + Initializes the toolchains needed to be able to build the Oppia proto API project. + + Note that this must be called after loading in this toolchains file, for example: + + load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") + initializeToolchainsForWorkspace() + + Note also that this can't be called until the dependencies themselves are loaded (see deps.bzl). + """ # Set up the toolchains for rules_proto. rules_proto_dependencies() rules_proto_toolchains() From fcf4a601a214bbcaf8a89efba291e8212b4bfdd8 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 29 Oct 2021 07:38:12 +0530 Subject: [PATCH 29/51] move dir to org/oppia/ --- .gitignore | 1 + BUILD | 8 ++++---- WORKSPACE | 4 ++-- {proto => org/oppia/proto}/BUILD | 0 {proto => org/oppia/proto}/v1/BUILD | 0 {proto => org/oppia/proto}/v1/api/BUILD | 4 ++-- {proto => org/oppia/proto}/v1/api/android.proto | 0 {proto => org/oppia/proto}/v1/structure/BUILD | 2 +- .../oppia/proto}/v1/structure/concept_card.proto | 0 {proto => org/oppia/proto}/v1/structure/exploration.proto | 0 {proto => org/oppia/proto}/v1/structure/image.proto | 0 {proto => org/oppia/proto}/v1/structure/languages.proto | 0 {proto => org/oppia/proto}/v1/structure/objects.proto | 0 {proto => org/oppia/proto}/v1/structure/question.proto | 0 .../oppia/proto}/v1/structure/revision_card.proto | 0 {proto => org/oppia/proto}/v1/structure/state.proto | 0 .../oppia/proto}/v1/structure/topic_summary.proto | 0 {proto => org/oppia/proto}/v1/versions/BUILD.bazel | 0 {proto => org/oppia/proto}/v1/versions/api_versions.proto | 0 .../oppia/proto}/v1/versions/structure_versions.proto | 0 {repo => org/oppia/repo}/BUILD | 0 {repo => org/oppia/repo}/deps.bzl | 0 {repo => org/oppia/repo}/toolchains.bzl | 0 23 files changed, 10 insertions(+), 9 deletions(-) create mode 100644 .gitignore rename {proto => org/oppia/proto}/BUILD (100%) rename {proto => org/oppia/proto}/v1/BUILD (100%) rename {proto => org/oppia/proto}/v1/api/BUILD (80%) rename {proto => org/oppia/proto}/v1/api/android.proto (100%) rename {proto => org/oppia/proto}/v1/structure/BUILD (93%) rename {proto => org/oppia/proto}/v1/structure/concept_card.proto (100%) rename {proto => org/oppia/proto}/v1/structure/exploration.proto (100%) rename {proto => org/oppia/proto}/v1/structure/image.proto (100%) rename {proto => org/oppia/proto}/v1/structure/languages.proto (100%) rename {proto => org/oppia/proto}/v1/structure/objects.proto (100%) rename {proto => org/oppia/proto}/v1/structure/question.proto (100%) rename {proto => org/oppia/proto}/v1/structure/revision_card.proto (100%) rename {proto => org/oppia/proto}/v1/structure/state.proto (100%) rename {proto => org/oppia/proto}/v1/structure/topic_summary.proto (100%) rename {proto => org/oppia/proto}/v1/versions/BUILD.bazel (100%) rename {proto => org/oppia/proto}/v1/versions/api_versions.proto (100%) rename {proto => org/oppia/proto}/v1/versions/structure_versions.proto (100%) rename {repo => org/oppia/repo}/BUILD (100%) rename {repo => org/oppia/repo}/deps.bzl (100%) rename {repo => org/oppia/repo}/toolchains.bzl (100%) diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..6d8ad95 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +bazel-* \ No newline at end of file diff --git a/BUILD b/BUILD index 993d07a..a97f945 100644 --- a/BUILD +++ b/BUILD @@ -17,7 +17,7 @@ package_group( package_group( name = "proto_impl_visibility", packages = [ - "//proto/...", + "//org/oppia/proto/...", ], ) @@ -30,9 +30,9 @@ proto_library( name = "android_protos", visibility = ["//visibility:public"], deps = [ - "//proto/v1/api:android_proto", - "//proto/v1/structure:structure_proto", - "//proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/api:android_proto", + "//org/oppia/proto/v1/structure:structure_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) diff --git a/WORKSPACE b/WORKSPACE index b7156f6..428217c 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -2,10 +2,10 @@ The top-level WORKSPACE definition for the Oppia proto API Bazel workspace. """ -load("//repo:deps.bzl", "initializeDepsForWorkspace") +load("//org/oppia/repo:deps.bzl", "initializeDepsForWorkspace") initializeDepsForWorkspace() -load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") +load("//org/oppia/repo:toolchains.bzl", "initializeToolchainsForWorkspace") initializeToolchainsForWorkspace() diff --git a/proto/BUILD b/org/oppia/proto/BUILD similarity index 100% rename from proto/BUILD rename to org/oppia/proto/BUILD diff --git a/proto/v1/BUILD b/org/oppia/proto/v1/BUILD similarity index 100% rename from proto/v1/BUILD rename to org/oppia/proto/v1/BUILD diff --git a/proto/v1/api/BUILD b/org/oppia/proto/v1/api/BUILD similarity index 80% rename from proto/v1/api/BUILD rename to org/oppia/proto/v1/api/BUILD index 2e4da12..39ef881 100644 --- a/proto/v1/api/BUILD +++ b/org/oppia/proto/v1/api/BUILD @@ -11,7 +11,7 @@ proto_library( strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. import_prefix = "org/oppia/proto/v1/api", # Make directory prefix match declared package. deps = [ - "//proto/v1/structure:structure_proto", - "//proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/structure:structure_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) diff --git a/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto similarity index 100% rename from proto/v1/api/android.proto rename to org/oppia/proto/v1/api/android.proto diff --git a/proto/v1/structure/BUILD b/org/oppia/proto/v1/structure/BUILD similarity index 93% rename from proto/v1/structure/BUILD rename to org/oppia/proto/v1/structure/BUILD index 44cdea0..316ff23 100644 --- a/proto/v1/structure/BUILD +++ b/org/oppia/proto/v1/structure/BUILD @@ -24,6 +24,6 @@ proto_library( "//:proto_impl_visibility", ], deps = [ - "//proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) diff --git a/proto/v1/structure/concept_card.proto b/org/oppia/proto/v1/structure/concept_card.proto similarity index 100% rename from proto/v1/structure/concept_card.proto rename to org/oppia/proto/v1/structure/concept_card.proto diff --git a/proto/v1/structure/exploration.proto b/org/oppia/proto/v1/structure/exploration.proto similarity index 100% rename from proto/v1/structure/exploration.proto rename to org/oppia/proto/v1/structure/exploration.proto diff --git a/proto/v1/structure/image.proto b/org/oppia/proto/v1/structure/image.proto similarity index 100% rename from proto/v1/structure/image.proto rename to org/oppia/proto/v1/structure/image.proto diff --git a/proto/v1/structure/languages.proto b/org/oppia/proto/v1/structure/languages.proto similarity index 100% rename from proto/v1/structure/languages.proto rename to org/oppia/proto/v1/structure/languages.proto diff --git a/proto/v1/structure/objects.proto b/org/oppia/proto/v1/structure/objects.proto similarity index 100% rename from proto/v1/structure/objects.proto rename to org/oppia/proto/v1/structure/objects.proto diff --git a/proto/v1/structure/question.proto b/org/oppia/proto/v1/structure/question.proto similarity index 100% rename from proto/v1/structure/question.proto rename to org/oppia/proto/v1/structure/question.proto diff --git a/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto similarity index 100% rename from proto/v1/structure/revision_card.proto rename to org/oppia/proto/v1/structure/revision_card.proto diff --git a/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto similarity index 100% rename from proto/v1/structure/state.proto rename to org/oppia/proto/v1/structure/state.proto diff --git a/proto/v1/structure/topic_summary.proto b/org/oppia/proto/v1/structure/topic_summary.proto similarity index 100% rename from proto/v1/structure/topic_summary.proto rename to org/oppia/proto/v1/structure/topic_summary.proto diff --git a/proto/v1/versions/BUILD.bazel b/org/oppia/proto/v1/versions/BUILD.bazel similarity index 100% rename from proto/v1/versions/BUILD.bazel rename to org/oppia/proto/v1/versions/BUILD.bazel diff --git a/proto/v1/versions/api_versions.proto b/org/oppia/proto/v1/versions/api_versions.proto similarity index 100% rename from proto/v1/versions/api_versions.proto rename to org/oppia/proto/v1/versions/api_versions.proto diff --git a/proto/v1/versions/structure_versions.proto b/org/oppia/proto/v1/versions/structure_versions.proto similarity index 100% rename from proto/v1/versions/structure_versions.proto rename to org/oppia/proto/v1/versions/structure_versions.proto diff --git a/repo/BUILD b/org/oppia/repo/BUILD similarity index 100% rename from repo/BUILD rename to org/oppia/repo/BUILD diff --git a/repo/deps.bzl b/org/oppia/repo/deps.bzl similarity index 100% rename from repo/deps.bzl rename to org/oppia/repo/deps.bzl diff --git a/repo/toolchains.bzl b/org/oppia/repo/toolchains.bzl similarity index 100% rename from repo/toolchains.bzl rename to org/oppia/repo/toolchains.bzl From eabbdf265ebcdb16b9a395bfed345b532c5fd656 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 7 Dec 2021 14:00:19 +0530 Subject: [PATCH 30/51] adding 4 more exploration --- org/oppia/proto/v1/structure/state.proto | 322 ++++++++++++++++++++++- 1 file changed, 321 insertions(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index a8314ec..66057bd 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -94,9 +94,17 @@ message InteractionInstance { // An interaction for inputting ratios. RatioExpressionInputInstance ratio_expression_input = 9; + AlgebraicExpressionInputInstance algebraic_expression_input = 10; + + MathEquationInputInstance MathEquationInput = 11; + + NumericExpressionInputInstance numeric_expression_input = 12; + + NumberWithUnitsInstance number_with_units = 13; + // An interaction that represents the end of an exploration and takes no direct user input other // than navigating away from the exploration. This is not used in question play sessions. - EndExplorationInstance end_exploration = 10; + EndExplorationInstance end_exploration = 14; } } @@ -1094,6 +1102,318 @@ message RatioExpressionInputInstance { } } +message AlgebraicExpressionInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + CustomizationArgs customization_args = 1; + + Outcome default_outcome = 2; + + repeated Hint hints = 3; + + repeated AnswerGroup answer_groups = 4; + + Solution solution = 5; + + message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + repeated string value = 1; + } + + message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the answer group. + BaseAnswerGroup base_answer_group = 1; + + // The list of all rules to match for this answer group. + repeated RuleSpec rule_specs = 2; + } + + message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + oneof rule_type { + MatchesExactlyWithSpec matches_exactly_with = 1; + + IsEquivalentToSpec is_equivalent_to = 2; + + ContainsSomeOfSpec contains_some_of = 3; + + OmitsSomeOfSpec omits_some_of = 4; + + MatchesWithGeneralFormSpec matches_with_general_form = 5; + } + + message MatchesExactlyWithSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message IsEquivalentToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message ContainsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message OmitsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message MatchesWithGeneralFormSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + + repeated string list = 2; + } + } + + message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the solution. + BaseSolution base_solution = 1; + + // The correct answer for this interaction that should be shown to the user. + string correct_answer = 2; + } +} + +message MathEquationInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + CustomizationArgs customization_args = 1; + + Outcome default_outcome = 2; + + repeated Hint hints = 3; + + repeated AnswerGroup answer_groups = 4; + + Solution solution = 5; + + message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + repeated string value = 1; + } + + message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the answer group. + BaseAnswerGroup base_answer_group = 1; + + // The list of all rules to match for this answer group. + repeated RuleSpec rule_specs = 2; + } + + message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + oneof rule_type { + MatchesExactlyWithSpec matches_exactly_with = 1; + + IsEquivalentToSpec is_equivalent_to = 2; + + ContainsSomeOfSpec contains_some_of = 3; + + OmitsSomeOfSpec omits_some_of = 4; + + MatchesWithGeneralFormSpec matches_with_general_form = 5; + } + + message MatchesExactlyWithSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + + string positionOfTerms = 2; + } + + message IsEquivalentToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message ContainsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + + string positionOfTerms = 2; + } + + message OmitsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + + string positionOfTerms = 2; + } + + message MatchesWithGeneralFormSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string input = 1; + + repeated string list = 2; + } + } + + message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the solution. + BaseSolution base_solution = 1; + + // The correct answer for this interaction that should be shown to the user. + string correct_answer = 2; + } +} + +message NumericExpressionInputInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + CustomizationArgs customization_args = 1; + + Outcome default_outcome = 2; + + repeated Hint hints = 3; + + repeated AnswerGroup answer_groups = 4; + + Solution solution = 5; + + message CustomizationArgs { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + SubtitledText placeholder = 1; + } + + message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the answer group. + BaseAnswerGroup base_answer_group = 1; + + // The list of all rules to match for this answer group. + repeated RuleSpec rule_specs = 2; + } + + message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + oneof rule_type { + MatchesExactlyWithSpec matches_exactly_with = 1; + + IsEquivalentToSpec is_equivalent_to = 2; + + ContainsSomeOfSpec contains_some_of = 3; + + OmitsSomeOfSpec omits_some_of = 4; + } + + message MatchesExactlyWithSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message IsEquivalentToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message ContainsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + + message OmitsSomeOfSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + string inputString = 1; + } + } + + message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the solution. + BaseSolution base_solution = 1; + + // The correct answer for this interaction that should be shown to the user. + string correct_answer = 2; + } +} + +message NumberWithUnitsInstance { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + Outcome default_outcome = 1; + + repeated AnswerGroup answer_groups = 2; + + Solution solution = 3; + + message AnswerGroup { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the answer group. + BaseAnswerGroup base_answer_group = 1; + + // The list of all rules to match for this answer group. + repeated RuleSpec rule_specs = 2; + } + + message RuleSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + oneof rule_type { + IsEqualToSpec is_equal_to = 1; + + IsEquivalentToSpec is_equivalent_to = 2; + } + + message IsEqualToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + Fraction input = 1; + } + + message IsEquivalentToSpec { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + Fraction input = 1; + } + } + + message Solution { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the solution. + BaseSolution base_solution = 1; + + // The correct answer for this interaction that should be shown to the user. + Fraction correct_answer = 2; + } +} + // Represents an interaction where the user has reached the end of the exploration, and has the // choice to navigate away from it. Details: // - Answer type: none (N/A since no answers are submitted for this interaction) From 937c883f921ebd6ace8acaeecb83cee61078062c Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 7 Dec 2021 14:06:03 +0530 Subject: [PATCH 31/51] added 4 more exploration ad nupdate to Dto suffix --- .../proto/v1/structure/concept_card.proto | 18 +- .../proto/v1/structure/exploration.proto | 6 +- org/oppia/proto/v1/structure/image.proto | 4 +- org/oppia/proto/v1/structure/languages.proto | 30 +- org/oppia/proto/v1/structure/objects.proto | 32 +- org/oppia/proto/v1/structure/question.proto | 6 +- .../proto/v1/structure/revision_card.proto | 16 +- org/oppia/proto/v1/structure/state.proto | 630 +++++++++--------- .../proto/v1/structure/topic_summary.proto | 24 +- 9 files changed, 383 insertions(+), 383 deletions(-) diff --git a/org/oppia/proto/v1/structure/concept_card.proto b/org/oppia/proto/v1/structure/concept_card.proto index 583b4df..6d0676b 100644 --- a/org/oppia/proto/v1/structure/concept_card.proto +++ b/org/oppia/proto/v1/structure/concept_card.proto @@ -13,7 +13,7 @@ option java_multiple_files = true; // to have exactly one concept card associated with them. Concept cards provide a lightweight // reminder experience for learners that can help them get unstuck when they might have forgotten // aspects of a certain skill that they need to demonstrate in a practice session or exploration. -message ConceptCard { +message ConceptCardDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; // The version defining the internal structure of this message. @@ -26,20 +26,20 @@ message ConceptCard { string description = 3; // The localizable explanation of the skill that is to be shown in the concept card. - SubtitledText explanation = 4; + SubtitledTextDto explanation = 4; // A list of worked examples to present to the learner. - repeated WorkedExample worked_examples = 5; + repeated WorkedExampleDto worked_examples = 5; // The recorded voiceovers for SubtitledText subfields of this concept card. - RecordedVoiceovers recorded_voiceovers = 6; + RecordedVoiceoversDto recorded_voiceovers = 6; // The translations of SubtitledText subfields of this concept card. - WrittenTranslations written_translations = 7; + WrittenTranslationsDto written_translations = 7; // The list of all images that are included within SubtitledText subfields of this concept card. // This is expected to include all references images, including in translations. - ReferencedImageList referenced_image_list = 8; + ReferencedImageListDto referenced_image_list = 8; // The version of the contents of this concept card (which corresponds to the 'version' field for // the concept card's skill on the server). @@ -47,13 +47,13 @@ message ConceptCard { // Represents a worked example (which provides a sample question and answer for the learner to // read and learn from). - message WorkedExample { + message WorkedExampleDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; // The localizable question for this worked example. - SubtitledText question = 1; + SubtitledTextDto question = 1; // The localizable explanation for how to solve this worked example. - SubtitledText explanation = 2; + SubtitledTextDto explanation = 2; } } diff --git a/org/oppia/proto/v1/structure/exploration.proto b/org/oppia/proto/v1/structure/exploration.proto index 2d9d84c..f1b2f91 100644 --- a/org/oppia/proto/v1/structure/exploration.proto +++ b/org/oppia/proto/v1/structure/exploration.proto @@ -11,7 +11,7 @@ option java_multiple_files = true; // Represents a single exploration that can be played by a learner. Explorations are interactive // lessons that are meant to teach or build on specific skills. -message Exploration { +message ExplorationDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = EXPLORATION_PROTO_VERSION; // The version defining the internal structure of this message. @@ -29,12 +29,12 @@ message Exploration { // The mapping from state names to state objects. State names are not meant to be // learner-readable. - map states = 5; + map states = 5; // The version of the contents of this exploration (which corresponds to the 'version' field on // the server). uint32 content_version = 6; // A list of all the images contained in SubtitledText subfields of this exploration. - ReferencedImageList referenced_image_list = 7; + ReferencedImageListDto referenced_image_list = 7; } diff --git a/org/oppia/proto/v1/structure/image.proto b/org/oppia/proto/v1/structure/image.proto index a315223..d1a1545 100644 --- a/org/oppia/proto/v1/structure/image.proto +++ b/org/oppia/proto/v1/structure/image.proto @@ -14,7 +14,7 @@ option java_multiple_files = true; // - Revision card thumbnails should work in 4:3 contexts // - Chapter (exploration) thumbnaisl should work in 16:9 contexts // - All other thumbnails should default to 4:3 (since that can be made workable to 16:9) -message Thumbnail { +message ThumbnailDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; // The version defining the internal structure of this message. @@ -38,7 +38,7 @@ message Thumbnail { } // Represents a list of images that may be referenced by various topic structures. -message ReferencedImageList { +message ReferencedImageListDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; // The version defining the internal structure of this message. diff --git a/org/oppia/proto/v1/structure/languages.proto b/org/oppia/proto/v1/structure/languages.proto index cff5cf9..bb22cae 100644 --- a/org/oppia/proto/v1/structure/languages.proto +++ b/org/oppia/proto/v1/structure/languages.proto @@ -51,7 +51,7 @@ enum LanguageType { // different Oppia's backend structures ('SubtitledHtml' and 'SubtitledUnicode'). Protobuf takes // care of properly representing Unicode strings internally by using UTF-8 encoding, so no special // care is needed by implementations or clients. -message SubtitledText { +message SubtitledTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The version defining the internal structure of this message. @@ -70,7 +70,7 @@ message SubtitledText { // Represents a group of voiceovers that correspond to subtitled texts in a particular content // context (such as a revision card or a 'State' in an exploration). -message RecordedVoiceovers { +message RecordedVoiceoversDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The version defining the internal structure of this message. @@ -78,22 +78,22 @@ message RecordedVoiceovers { // A list of mappings from language to voiceover content mappings (see the message's documentation // for specifics on the latter). - repeated VoiceoverContentMapping voiceover_content_mapping = 2; + repeated VoiceoverContentMappingDto voiceover_content_mapping = 2; } // Represents a mapping of SubtitledText content IDs to voiceovers for a particular language. -message VoiceoverContentMapping { +message VoiceoverContentMappingDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The language corresponding to this mapping. LanguageType language = 1; // The mapping of SubtitledText content IDs to their corresponding voiceover files. - map voiceover_content_mapping = 2; + map voiceover_content_mapping = 2; } // Represents an audio file that, when played, reads out content text in a particular language. -message VoiceoverFile { +message VoiceoverFileDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The name of the voiceover audio file. This will never be a URL (and can always be expected to @@ -113,7 +113,7 @@ message VoiceoverFile { // Represents a group of written translations that correspond to subtitled texts in a particular // content context (such as a revision card or a 'State' in an exploration). -message WrittenTranslations { +message WrittenTranslationsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The version defining the internal structure of this message. @@ -121,38 +121,38 @@ message WrittenTranslations { // A list of mappings from language to written translation content mappings (see the message's // documentation for specifics on the latter). - repeated WrittenTranslationContentMapping translation_language_mapping = 2; + repeated WrittenTranslationContentMappingDto translation_language_mapping = 2; } // Represents a mapping of SubtitledText content IDs to written translations for a particular // language. -message WrittenTranslationContentMapping { +message WrittenTranslationContentMappingDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The language corresponding to this mapping. LanguageType language = 1; // The mapping of SubtitledText content IDs to their corresponding written translations. - map translation_content_mapping = 2; + map translation_content_mapping = 2; } // Represents a single textual translation of specific content text in a particular language. -message WrittenTranslation { +message WrittenTranslationDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The data format of the source material for this translation. oneof data_format { // Indicates that this translation corresponds to a single piece of text. - WrittenTranslatableText translatable_text = 1; + WrittenTranslatableTextDto translatable_text = 1; // Indicates that this translation corresponds to a list of translated texts. - SetOfWrittenTranslatableText set_of_translatable_text = 2; + SetOfWrittenTranslatableTextDto set_of_translatable_text = 2; } } // Represents the translation of a single text string (which may be either plain text or HTML, and // is generally expected to potentially contain Unicode characters). -message WrittenTranslatableText { +message WrittenTranslatableTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The human-readable translated string. @@ -165,7 +165,7 @@ message WrittenTranslatableText { // Note that while the list of translated strings roughly corresponds to the original source // material (i.e. the default, untranslated content strings specified directly in SubtitledText), // neither the order nor the length are expected to exactly match. -message SetOfWrittenTranslatableText { +message SetOfWrittenTranslatableTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The list of human-readable translated strings. diff --git a/org/oppia/proto/v1/structure/objects.proto b/org/oppia/proto/v1/structure/objects.proto index eb04013..b7a4c32 100644 --- a/org/oppia/proto/v1/structure/objects.proto +++ b/org/oppia/proto/v1/structure/objects.proto @@ -9,7 +9,7 @@ option java_multiple_files = true; // Anything not typed to rule inputs should go into the correct file with the correct versions. // Proto message representing a single fraction or mixed number. -message Fraction { +message FractionDto { // Whether the fraction is negative. bool is_negative = 1; @@ -26,25 +26,25 @@ message Fraction { // Proto representing a single content ID for an HTML field. This content ID is used to map HTML // fields to their corresponding translations and voiceovers (see e.g. the WrittenTranslations // substructure of the corresponding State). -message TranslatableHtmlContentId { +message TranslatableHtmlContentIdDto { // The content ID for the HTML field, which is unique within a given State. string content_id = 1; } // Proto representing a set of TranslatableHtmlContentIds. -message SetOfTranslatableHtmlContentIds { +message SetOfTranslatableHtmlContentIdsDto { // The set of content IDs. - repeated TranslatableHtmlContentId content_ids = 1; + repeated TranslatableHtmlContentIdDto content_ids = 1; } // Proto representing a list of SetOfTranslatableHtmlContentIds. -message ListOfSetsOfTranslatableHtmlContentIds { +message ListOfSetsOfTranslatableHtmlContentIdsDto { // The sets of content IDs. - repeated SetOfTranslatableHtmlContentIds content_id_sets = 1; + repeated SetOfTranslatableHtmlContentIdsDto content_id_sets = 1; } // Proto representing a 2D point for the ImageRegion interaction type. -message NormalizedPoint2d { +message NormalizedPoint2dDto { // Relative x-coordinate of the point within the image. This lies within the range [0, 1] and // measures horizontal distance (with the left boundary of the image as the origin). @@ -56,7 +56,7 @@ message NormalizedPoint2d { } // Proto representing a ratio object in list form, e.g. [1,2,3] for 1:2:3. -message RatioExpression { +message RatioExpressionDto { // List of components in the ratio. The list is expected to have more than one element. repeated uint32 components = 1; } @@ -65,7 +65,7 @@ message RatioExpression { // which may check the learner's answer against one of a given set of strings. The corresponding // replacement strings for a different language can be found in the WrittenTranslations structure of // the containing State. -message TranslatableSetOfNormalizedString { +message TranslatableSetOfNormalizedStringDto { // The content ID corresponding to this set of normalized strings. string content_id = 1; @@ -74,16 +74,16 @@ message TranslatableSetOfNormalizedString { } // Proto representing an image that is overlaid with labeled regions. -message ImageWithRegions { +message ImageWithRegionsDto { // The filepath of the image, which will be prefixed with '[exploration_id]/assets'. string image_file_path = 1; // The labeled regions of this image. - repeated LabeledRegion labeled_regions = 2; + repeated LabeledRegionDto labeled_regions = 2; // Proto representing a labeled region of the image. - message LabeledRegion { + message LabeledRegionDto { // The name of the region's label. string label = 3; @@ -91,19 +91,19 @@ message ImageWithRegions { oneof region_type { // A rectangle that is normalized so that its boundary coordinates are within the range [0,1], // where 0 corresponds to one end of the image and 1 to the other. - NormalizedRectangle2d normalized_rectangle_2d = 1; + NormalizedRectangle2dDto normalized_rectangle_2d = 1; } // Proto representing a 2D rectangle defined using normalized coordinates relative to the image. // The origin of the coordinate system is at the top left of the image. The x-coordinate // measures horizontal distance (to the right), and the y-coordinate measures vertical distance // (downwards). - message NormalizedRectangle2d { + message NormalizedRectangle2dDto { // The top-left corner of the rectangle, in normalized coordinates. - NormalizedPoint2d top_left = 1; + NormalizedPoint2dDto top_left = 1; // The bottom-right corner of the rectangle, in normalized coordinates. - NormalizedPoint2d bottom_right = 2; + NormalizedPoint2dDto bottom_right = 2; } } } diff --git a/org/oppia/proto/v1/structure/question.proto b/org/oppia/proto/v1/structure/question.proto index 36caf2d..ee04927 100644 --- a/org/oppia/proto/v1/structure/question.proto +++ b/org/oppia/proto/v1/structure/question.proto @@ -15,7 +15,7 @@ option java_multiple_files = true; // // Questions are not directly tied to topics, but clients are expected to initiate training sessions // by picking questions that correspond to the skills of the topic's subtopics. -message Question { +message QuestionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = QUESTION_PROTO_VERSION; // The version defining the internal structure of this message. @@ -25,7 +25,7 @@ message Question { string id = 2; // The State object that makes up the main part of this question. - State question_state = 3; + StateDto question_state = 3; // The list of all skill IDs that are linked to this question. repeated string linked_skill_ids = 4; @@ -34,5 +34,5 @@ message Question { uint32 content_version = 5; // The list of all images that are included within SubtitledText subfields of this question. - ReferencedImageList referenced_image_list = 6; + ReferencedImageListDto referenced_image_list = 6; } diff --git a/org/oppia/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto index f8c48eb..fe9e764 100644 --- a/org/oppia/proto/v1/structure/revision_card.proto +++ b/org/oppia/proto/v1/structure/revision_card.proto @@ -16,36 +16,36 @@ option java_multiple_files = true; // // Topics may contain one or more subtopics, but subtopics only ever belong to a single topic. // Each subtopic always has a single corresponding revision card. -message RevisionCard { +message RevisionCardDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = REVISION_CARD_PROTO_VERSION; // The version defining the internal structure of this message. org.oppia.proto.v1.versions.RevisionCardProtoVersion proto_version = 1; // The structured ID of the subtopic corresponding to this revision card. - SubtopicId id = 2; + SubtopicIdDto id = 2; // The human-readable title of the revision card. This is expected to be in English. string title = 3; // The main content of this revision card. - SubtitledText content = 4; + SubtitledTextDto content = 4; // The recorded voiceovers for SubtitledText subfields of this revision card. - RecordedVoiceovers recorded_voiceovers = 5; + RecordedVoiceoversDto recorded_voiceovers = 5; // The written translations for SubtitledText subfields of this revision card. - WrittenTranslations written_translations = 6; + WrittenTranslationsDto written_translations = 6; // The thumbnail image for this revision card. - Thumbnail thumbnail = 7; + ThumbnailDto thumbnail = 7; // The list of all images that are included within SubtitledText subfields of this revision card. - ReferencedImageList referenced_image_list = 8; + ReferencedImageListDto referenced_image_list = 8; } // Represents the identifier for a subtopic (which are tightly tied to specific topics). -message SubtopicId { +message SubtopicIdDto { // This proto message type is shared among multiple protos, so it has no direct migration pathway. // Changes here should be carefully done in a way that does not break compatibility or assumptions // across all relevant proto versions, or the proto should be duplicated according to whichever diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index 66057bd..3ed3265 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -15,24 +15,24 @@ option java_multiple_files = true; // fractions or text). When users submit answers to this interaction, they receive feedback in the // form of a textual response and may be routed to the same state, or to a new state (which may be a // repeat of one they've completed in the past). -message State { +message StateDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The version defining the internal structure of this message. org.oppia.proto.v1.versions.StateProtoVersion proto_version = 1; // The main content of the state which is the first thing shown to a learner viewing this state. - SubtitledText content = 2; + SubtitledTextDto content = 2; // The interaction of the state (which must be interacted with by the learner in order to // proceed). - InteractionInstance interaction = 3; + InteractionInstanceDto interaction = 3; // The recorded voiceovers for SubtitledText subfields of this state. - RecordedVoiceovers recorded_voiceovers = 4; + RecordedVoiceoversDto recorded_voiceovers = 4; // The translations of SubtitledText subfields of this state. - WrittenTranslations written_translations = 5; + WrittenTranslationsDto written_translations = 5; } // Represents an instance of a single interaction within a state. Note that interactions are @@ -62,49 +62,49 @@ message State { // Finally, interactions may have 'customization arguments' which are creator-provided options to // specialize the interaction for that particular context (such as tweaking hint or placeholder text // for input boxes). -message InteractionInstance { +message InteractionInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The type of the interaction. oneof interaction_type { // An interaction that takes the form of a simple 'Continue' button. - ContinueInstance continue_instance = 1; + ContinueInstanceDto continue_instance = 1; // An interaction for inputting fractions. - FractionInputInstance fraction_input = 2; + FractionInputInstanceDto fraction_input = 2; // An interaction for selecting one or more items from a list. - ItemSelectionInputInstance item_selection_input = 3; + ItemSelectionInputInstanceDto item_selection_input = 3; // An interaction for selecting a single option among multiple presented choices. - MultipleChoiceInputInstance multiple_choice_input = 4; + MultipleChoiceInputInstanceDto multiple_choice_input = 4; // An interaction for inputting numbers. - NumericInputInstance numeric_input = 5; + NumericInputInstanceDto numeric_input = 5; // An interaction for inputting a line of text. - TextInputInstance text_input = 6; + TextInputInstanceDto text_input = 6; // An interaction for rearranging a list of items by dragging & dropping them. - DragAndDropSortInputInstance drag_and_drop_sort_input = 7; + DragAndDropSortInputInstanceDto drag_and_drop_sort_input = 7; // An interaction for selecting a learner-identified part of an image. - ImageClickInputInstance image_click_input = 8; + ImageClickInputInstanceDto image_click_input = 8; // An interaction for inputting ratios. - RatioExpressionInputInstance ratio_expression_input = 9; + RatioExpressionInputInstanceDto ratio_expression_input = 9; - AlgebraicExpressionInputInstance algebraic_expression_input = 10; + AlgebraicExpressionInputInstanceDto algebraic_expression_input = 10; - MathEquationInputInstance MathEquationInput = 11; + MathEquationInputInstanceDto MathEquationInput = 11; - NumericExpressionInputInstance numeric_expression_input = 12; + NumericExpressionInputInstanceDto numeric_expression_input = 12; - NumberWithUnitsInstance number_with_units = 13; + NumberWithUnitsInstanceDto number_with_units = 13; // An interaction that represents the end of an exploration and takes no direct user input other // than navigating away from the exploration. This is not used in question play sessions. - EndExplorationInstance end_exploration = 14; + EndExplorationInstanceDto end_exploration = 14; } } @@ -113,25 +113,25 @@ message InteractionInstance { // - Has a default outcome: yes (it's actually the only outcome) // - Has support for showing hints: no // - Has support for showing a solution: no -message ContinueInstance { +message ContinueInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The default outcome for this interaction. - Outcome default_outcome = 2; + OutcomeDto default_outcome = 2; // Continue interactions cannot have custom answer groups, and do not support solutions. Users // cannot receive hints since only one answer is possible (clicking the button). // Represents the customization arguments available for instances of the continue interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Custom text to use for the 'Continue' button displayed for this interaction rather than using // the button's default text ('Continue'). - SubtitledText button_text = 1; + SubtitledTextDto button_text = 1; } } @@ -140,27 +140,27 @@ message ContinueInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: yes -message FractionInputInstance { +message FractionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // The solution corresponding to this interaction. - Solution solution = 5; + SolutionDto solution = 5; // Represents the customization arguments available for instances of the fraction input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Specifics whether fractions must be provided in simplest form (that is, '2/4' would not be @@ -177,117 +177,117 @@ message FractionInputInstance { // Specifies the placeholder/hint text that should be shown in the fraction input box prior to // the user starting to enter an answer. Note that this will override the client's default text. - SubtitledText placeholder = 4; + SubtitledTextDto placeholder = 4; } // Represents the specific solution available to instances of the fraction input interaction. - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. - Fraction correct_answer = 2; + FractionDto correct_answer = 2; } // Represents the specific answer group used by instances of the fraction input interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the fraction input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for fraction answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - IsExactlyEqualToSpec is_exactly_equal_to = 1; + IsExactlyEqualToSpecDto is_exactly_equal_to = 1; // See the specific message's documentation for details on this rule type. - IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToSpecDto is_equivalent_to = 2; // See the specific message's documentation for details on this rule type. - IsEquivalentToAndInSimplestFormSpec is_equivalent_to_and_in_simplest_form = 3; + IsEquivalentToAndInSimplestFormSpecDto is_equivalent_to_and_in_simplest_form = 3; // See the specific message's documentation for details on this rule type. - IsLessThanSpec is_less_than = 4; + IsLessThanSpecDto is_less_than = 4; // See the specific message's documentation for details on this rule type. - IsGreaterThanSpec is_greater_than = 5; + IsGreaterThanSpecDto is_greater_than = 5; // See the specific message's documentation for details on this rule type. - HasNumeratorEqualToSpec has_numerator_equal_to = 6; + HasNumeratorEqualToSpecDto has_numerator_equal_to = 6; // See the specific message's documentation for details on this rule type. - HasDenominatorEqualToSpec has_denominator_equal_to = 7; + HasDenominatorEqualToSpecDto has_denominator_equal_to = 7; // See the specific message's documentation for details on this rule type. - HasIntegerPartEqualToSpec has_integer_part_equal_to = 8; + HasIntegerPartEqualToSpecDto has_integer_part_equal_to = 8; // See the specific message's documentation for details on this rule type. - HasNoFractionalPartSpec has_no_fractional_part = 9; + HasNoFractionalPartSpecDto has_no_fractional_part = 9; // See the specific message's documentation for details on this rule type. - HasFractionalPartExactlyEqualToSpec has_fractional_part_exactly_equal_to = 10; + HasFractionalPartExactlyEqualToSpecDto has_fractional_part_exactly_equal_to = 10; } // Represents a rule spec for checking whether an answer exactly matches a creator-specified // fraction. - message IsExactlyEqualToSpec { + message IsExactlyEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } // Represents a rule spec for checking whether an answer is equivalent to a creator-specified // fraction (but not necessarily exactly the same). - message IsEquivalentToSpec { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } // Represents a rule spec for checking whether an answer is equivalent to a creator-specified // fraction, in a similar way to IsEquivalentToSpec, except this also requires that the user's // answer is in simplest form. - message IsEquivalentToAndInSimplestFormSpec { + message IsEquivalentToAndInSimplestFormSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } // Represents a rule spec for checking whether an answer is mathematically less than a // creator-specified fraction. - message IsLessThanSpec { + message IsLessThanSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } // Represents a rule spec for checking whether an answer is mathematically greater than a // creator-specified fraction. - message IsGreaterThanSpec { + message IsGreaterThanSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } // Represents a rule spec for checking whether an answer has a numerator equal to a // creator-specified numerator. - message HasNumeratorEqualToSpec { + message HasNumeratorEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified numerator to match against the user's answer. @@ -296,7 +296,7 @@ message FractionInputInstance { // Represents a rule spec for checking whether an answer has a denominator equal to a // creator-specified denominator. - message HasDenominatorEqualToSpec { + message HasDenominatorEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified denominator to match against the user's answer. @@ -305,7 +305,7 @@ message FractionInputInstance { // Represents a rule spec for checking whether an answer has an integer part equal to a // creator-specified integer part. - message HasIntegerPartEqualToSpec { + message HasIntegerPartEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified integer part to match against the user's answer. @@ -314,7 +314,7 @@ message FractionInputInstance { // Represents a rule spec for checking whether an answer is missing its fractional part (i.e. // that it's just a whole number). - message HasNoFractionalPartSpec { + message HasNoFractionalPartSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // No inputs for this rule spec. @@ -322,11 +322,11 @@ message FractionInputInstance { // Represents a rule spec for checking whether an answer has a fractional part exactly equal to // a creator-specified fraction (whose integer part is ignored during classification). - message HasFractionalPartExactlyEqualToSpec { + message HasFractionalPartExactlyEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified fraction to match against the user's answer. - Fraction input = 1; + FractionDto input = 1; } } } @@ -337,26 +337,26 @@ message FractionInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: no -message ItemSelectionInputInstance { +message ItemSelectionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // Item selection does not support solutions. // Represents the customization arguments available for instances of the item selection input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Specifies the minimum number of items that must be selected before an answer can be @@ -368,79 +368,79 @@ message ItemSelectionInputInstance { uint32 max_allowable_selection_count = 2; // The list of selectable items. - repeated SubtitledText choices = 3; + repeated SubtitledTextDto choices = 3; } // Represents the specific answer group used by instances of the item selection input interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the item selection input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for item selection answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - EqualsSpec equals = 1; + EqualsSpecDto equals = 1; // See the specific message's documentation for details on this rule type. - ContainsAtLeastOneOfSpec contains_at_least_one_of = 2; + ContainsAtLeastOneOfSpecDto contains_at_least_one_of = 2; // See the specific message's documentation for details on this rule type. - DoesNotContainAtLeastOneOfSpec does_not_contain_at_least_one_of = 3; + DoesNotContainAtLeastOneOfSpecDto does_not_contain_at_least_one_of = 3; // See the specific message's documentation for details on this rule type. - IsProperSubsetOfSpec is_proper_subset_of = 4; + IsProperSubsetOfSpecDto is_proper_subset_of = 4; } // Represents a rule spec for checking whether an answer has exactly the same items as a // creator-specified list of item selections. Note that order does not matter for these items. - message EqualsSpec { + message EqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified list of item selections to match against the user's // answer. - SetOfTranslatableHtmlContentIds input = 1; + SetOfTranslatableHtmlContentIdsDto input = 1; } // Represents a rule spec for checking whether an answer has at least one of the items defined // in a creator-specified list of item selections. Note that order does not matter for these // items. - message ContainsAtLeastOneOfSpec { + message ContainsAtLeastOneOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified list of item selections to match against the user's // answer. - SetOfTranslatableHtmlContentIds input = 1; + SetOfTranslatableHtmlContentIdsDto input = 1; } // Represents a rule spec for checking whether an answer has none of the items defined in a // creator-specified list of item selections. Note that order does not matter for these items. - message DoesNotContainAtLeastOneOfSpec { + message DoesNotContainAtLeastOneOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified list of item selections to match against the user's // answer. - SetOfTranslatableHtmlContentIds input = 1; + SetOfTranslatableHtmlContentIdsDto input = 1; } // Represents a rule spec for checking whether an answer is a proper subset of a // creator-specified list of item selections (treated as a set), that is, that it's fully // contained in the creator-specified set but is not exactly equal to it. - message IsProperSubsetOfSpec { + message IsProperSubsetOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified list of item selections to match against the user's // answer. - SetOfTranslatableHtmlContentIds input = 1; + SetOfTranslatableHtmlContentIdsDto input = 1; } } } @@ -450,57 +450,57 @@ message ItemSelectionInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: no -message MultipleChoiceInputInstance { +message MultipleChoiceInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // Multiple choice does not support solutions. // Represents the customization arguments available for instances of the multiple choice input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The list of selectable items. - repeated SubtitledText choices = 1; + repeated SubtitledTextDto choices = 1; } // Represents the specific answer group used by instances of the multiple choice input // interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the multiple choice input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for multiple choice answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - EqualsSpec equals = 1; + EqualsSpecDto equals = 1; } // Represents a rule spec for checking whether an answer matches to a creator-specified multiple // choice option index. - message EqualsSpec { + message EqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified multiple choice option index to match against the @@ -515,77 +515,77 @@ message MultipleChoiceInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: yes -message NumericInputInstance { +message NumericInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 1; + repeated AnswerGroupDto answer_groups = 1; // The default outcome for this interaction. - Outcome default_outcome = 2; + OutcomeDto default_outcome = 2; // The hints corresponding to this interaction. - repeated Hint hints = 3; + repeated HintDto hints = 3; // The solution corresponding to this interaction. - Solution solution = 4; + SolutionDto solution = 4; // Numeric input does not have any customization arguments. // Represents the specific solution available to instances of the numeric input interaction. - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. double correct_answer = 2; } // Represents the specific answer group used by instances of the numeric input interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the numeric input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for numeric input answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - EqualsSpec equals = 1; + EqualsSpecDto equals = 1; // See the specific message's documentation for details on this rule type. - IsLessThanSpec is_less_than = 2; + IsLessThanSpecDto is_less_than = 2; // See the specific message's documentation for details on this rule type. - IsGreaterThanSpec is_greater_than = 3; + IsGreaterThanSpecDto is_greater_than = 3; // See the specific message's documentation for details on this rule type. - IsLessThanOrEqualToSpec is_less_than_or_equal_to = 4; + IsLessThanOrEqualToSpecDto is_less_than_or_equal_to = 4; // See the specific message's documentation for details on this rule type. - IsGreaterThanOrEqualToSpec is_greater_than_or_equal_to = 5; + IsGreaterThanOrEqualToSpecDto is_greater_than_or_equal_to = 5; // See the specific message's documentation for details on this rule type. - IsInclusivelyBetweenSpec is_inclusively_between = 6; + IsInclusivelyBetweenSpecDto is_inclusively_between = 6; // See the specific message's documentation for details on this rule type. - IsWithinToleranceSpec is_within_tolerance = 7; + IsWithinToleranceSpecDto is_within_tolerance = 7; } // Represents a rule spec for checking whether an answer exactly* equals a creator-specified real // value. *Note that the match here uses an epsilon comparison to account for IEEE 754 floating // point rounding errors. - message EqualsSpec { + message EqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified real value to match against the user's answer. @@ -594,7 +594,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is numerically less than a // creator-specified real value. - message IsLessThanSpec { + message IsLessThanSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified real value to match against the user's answer. @@ -603,7 +603,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is numerically greater than a // creator-specified real value. - message IsGreaterThanSpec { + message IsGreaterThanSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified real value to match against the user's answer. @@ -612,7 +612,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is numerically less than or exactly // equal to a creator-specified real value. - message IsLessThanOrEqualToSpec { + message IsLessThanOrEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified real value to match against the user's answer. @@ -621,7 +621,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is numerically greater than or exactly // equal to a creator-specified real value. - message IsGreaterThanOrEqualToSpec { + message IsGreaterThanOrEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified real value to match against the user's answer. @@ -630,7 +630,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is within a creator-specified fully // closed/inclusive range. - message IsInclusivelyBetweenSpec { + message IsInclusivelyBetweenSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified inclusive lower bound for comparison against the @@ -644,7 +644,7 @@ message NumericInputInstance { // Represents a rule spec for checking whether an answer is equal to a creator-specified value // when accounting for a creator-specific tolerance range. - message IsWithinToleranceSpec { + message IsWithinToleranceSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified tolerance to consider when matching against the user's @@ -666,116 +666,116 @@ message NumericInputInstance { // Note that all answers submitted to this interaction undergo 'string normalization' which involves // trimming leading & trailing whitespace, removing all non-space whitespace, and replacing extra // spaces such that at most one space separates characters. -message TextInputInstance { +message TextInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // The solution corresponding to this interaction. - Solution solution = 5; + SolutionDto solution = 5; // Represents the customization arguments available for instances of the text input interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Specifies the placeholder/hint text that should be shown in the text input box prior to the // user starting to enter an answer. Note that this will override the client's default text. - SubtitledText placeholder = 1; + SubtitledTextDto placeholder = 1; // Specifies the number of rows (visual lines) that should be allowed for text input. uint32 rows = 2; } // Represents the specific solution available to instances of the text input interaction. - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. string correct_answer = 2; } // Represents the specific answer group used by instances of the text input interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the text input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for text input answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - EqualsSpec equals = 1; + EqualsSpecDto equals = 1; // See the specific message's documentation for details on this rule type. - StartsWithSpec starts_with = 2; + StartsWithSpecDto starts_with = 2; // See the specific message's documentation for details on this rule type. - ContainsSpec contains = 3; + ContainsSpecDto contains = 3; // See the specific message's documentation for details on this rule type. - FuzzyEqualsSpec fuzzy_equals = 4; + FuzzyEqualsSpecDto fuzzy_equals = 4; } // Represents a rule spec for checking whether an answer is exactly equal to (after string // normalization) to any of the strings in a creator-specified string list. - message EqualsSpec { + message EqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified set of text input values to match against the user's // answer. - TranslatableSetOfNormalizedString input = 1; + TranslatableSetOfNormalizedStringDto input = 1; } // Represents a rule spec for checking whether an answer starts with any of the strings in a // creator-specified string list (with string normalization). - message StartsWithSpec { + message StartsWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified set of text input values to match against the user's // answer. - TranslatableSetOfNormalizedString input = 1; + TranslatableSetOfNormalizedStringDto input = 1; } // Represents a rule spec for checking whether an answer contains any of the strings in a // creator-specified string list (with string normalization). - message ContainsSpec { + message ContainsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified set of text input values to match against the user's // answer. - TranslatableSetOfNormalizedString input = 1; + TranslatableSetOfNormalizedStringDto input = 1; } // Represents a rule spec for checking whether an answer fuzzily equals any of the strings in a // creator-specified string list (with string normalization), that is, whether it equals one of // the strings with at most one character misspelled. - message FuzzyEqualsSpec { + message FuzzyEqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified set of text input values to match against the user's // answer. - TranslatableSetOfNormalizedString input = 1; + TranslatableSetOfNormalizedStringDto input = 1; } } } @@ -786,31 +786,31 @@ message TextInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: yes -message DragAndDropSortInputInstance { +message DragAndDropSortInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // The solution corresponding to this interaction. - Solution solution = 5; + SolutionDto solution = 5; // Represents the customization arguments available for instances of the drag and drop sort input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The list of items that can be dragged & dropped. - repeated SubtitledText choices = 1; + repeated SubtitledTextDto choices = 1; // Specifies whether items can be allowed at the same position in the list (i.e. linked or // unlinked). @@ -819,78 +819,78 @@ message DragAndDropSortInputInstance { // Represents the specific solution available to instances of the drag and drop sort input // interaction. - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. - ListOfSetsOfTranslatableHtmlContentIds correct_answer = 2; + ListOfSetsOfTranslatableHtmlContentIdsDto correct_answer = 2; } // Represents the specific answer group used by instances of the drag and drop sort input // interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the drag and drop sort input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for drag and drop answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - IsEqualToOrderingSpec is_equal_to_ordering = 1; + IsEqualToOrderingSpecDto is_equal_to_ordering = 1; // See the specific message's documentation for details on this rule type. - IsEqualToOrderingWithOneItemAtIncorrectPositionSpec is_equal_to_ordering_with_one_item_at_incorrect_position = 2; + IsEqualToOrderingWithOneItemAtIncorrectPositionSpecDto is_equal_to_ordering_with_one_item_at_incorrect_position = 2; // See the specific message's documentation for details on this rule type. - HasElementXAtPositionYSpec has_element_x_at_position_y = 3; + HasElementXAtPositionYSpecDto has_element_x_at_position_y = 3; // See the specific message's documentation for details on this rule type. - HasElementXBeforeElementYSpec has_element_x_before_element_y = 4; + HasElementXBeforeElementYSpecDto has_element_x_before_element_y = 4; } // Represents a rule spec for checking whether an answer exactly matches a creator-specified // drag and drop configuration (that is, a list of drag and drop items with some items // potentially on the same line), with ordering being considered. - message IsEqualToOrderingSpec { + message IsEqualToOrderingSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified drag and drop configuration to match against the // user's answer. - ListOfSetsOfTranslatableHtmlContentIds input = 1; + ListOfSetsOfTranslatableHtmlContentIdsDto input = 1; } // Represents a rule spec for checking whether an answer exactly matches a creator-specified // drag and drop configuration (that is, a list of drag and drop items with some items // potentially on the same line), with ordering being considered and with exactly one item being // in the incorrect position. - message IsEqualToOrderingWithOneItemAtIncorrectPositionSpec { + message IsEqualToOrderingWithOneItemAtIncorrectPositionSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified drag and drop configuration to match against the // user's answer. - ListOfSetsOfTranslatableHtmlContentIds input = 1; + ListOfSetsOfTranslatableHtmlContentIdsDto input = 1; } // Represents a rule spec for checking whether an answer has an element at a creator-specified // position exactly matched a creator-specified option (which should correspond to one of the // options defined in the interaction's customization arguments). - message HasElementXAtPositionYSpec { + message HasElementXAtPositionYSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified single element to match against the user's answer. - TranslatableHtmlContentId element = 1; + TranslatableHtmlContentIdDto element = 1; // Corresponds to the creator-specified element index with which to extract from the user's // answer a value to compare against the defined element. @@ -901,16 +901,16 @@ message DragAndDropSortInputInstance { // that one of the particular elements occurs before another one of the specified elements, // where both elements should correspond to options defined in the interaction's customization // arguments). - message HasElementXBeforeElementYSpec { + message HasElementXBeforeElementYSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified element that's expected to be contained in the user's // answer. - TranslatableHtmlContentId considered_element = 1; + TranslatableHtmlContentIdDto considered_element = 1; // Corresponds to the creator-specified element that's expected to be contained in the user's // answer. - TranslatableHtmlContentId later_element = 2; + TranslatableHtmlContentIdDto later_element = 2; } } } @@ -920,57 +920,57 @@ message DragAndDropSortInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: no -message ImageClickInputInstance { +message ImageClickInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // Image click input doesn't yet support solutions. // Represents the customization arguments available for instances of the image click input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Defines the image to display to the user, and all of the constituent regions that the user // may selected. - ImageWithRegions image_and_regions = 1; + ImageWithRegionsDto image_and_regions = 1; } // Represents the specific answer group used by instances of the image click input interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the image click input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for image click answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - IsInRegionSpec is_in_region = 1; + IsInRegionSpecDto is_in_region = 1; } // Represents a rule spec for checking whether an answer corresponds to a creator-specified // region (as a determination of that region being clicked by the user). - message IsInRegionSpec { + message IsInRegionSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified image region label to match against the user's answer. @@ -984,32 +984,32 @@ message ImageClickInputInstance { // - Has a default outcome: yes // - Has support for showing hints: yes // - Has support for showing a solution: yes -message RatioExpressionInputInstance { +message RatioExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The customization arguments for this interaction. - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; // The answer groups for this interaction. - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; // The default outcome for this interaction. - Outcome default_outcome = 3; + OutcomeDto default_outcome = 3; // The hints corresponding to this interaction. - repeated Hint hints = 4; + repeated HintDto hints = 4; // The solution corresponding to this interaction. - Solution solution = 5; + SolutionDto solution = 5; // Represents the customization arguments available for instances of the ratio expression input // interaction. - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Specifies the placeholder/hint text that should be shown in the ratio input box prior to the // user starting to enter an answer. Note that this will override the client's default text. - SubtitledText placeholder = 1; + SubtitledTextDto placeholder = 1; // The number of elements that the answer must have, or 0 to indicate that a ratio of any length // will be accepted. For example, if this is set to '5' then the ratio must have 5 components @@ -1019,68 +1019,68 @@ message RatioExpressionInputInstance { // Represents the specific solution available to instances of the ratio expression input // interaction. - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. - RatioExpression correct_answer = 2; + RatioExpressionDto correct_answer = 2; } // Represents the specific answer group used by instances of the ratio expression input // interaction. - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } // Represents specific rule specs used by instances of the ratio expression input interaction. - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Possible rule types for ratio expression answers. oneof rule_type { // See the specific message's documentation for details on this rule type. - EqualsSpec equals = 1; + EqualsSpecDto equals = 1; // See the specific message's documentation for details on this rule type. - IsEquivalentSpec is_equivalent = 2; + IsEquivalentSpecDto is_equivalent = 2; // See the specific message's documentation for details on this rule type. - HasNumberOfTermsEqualToSpec has_number_of_terms_equal_to = 3; + HasNumberOfTermsEqualToSpecDto has_number_of_terms_equal_to = 3; // See the specific message's documentation for details on this rule type. - HasSpecificTermEqualToSpec has_specific_term_equal_to = 4; + HasSpecificTermEqualToSpecDto has_specific_term_equal_to = 4; } // Represents a rule spec for checking whether an answer exactly equals a creator-specified // ratio expression. - message EqualsSpec { + message EqualsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified ratio expression to match against the user's answer. - RatioExpression input = 1; + RatioExpressionDto input = 1; } // Represents a rule spec for checking whether an answer is equivalent to a creator-specified // ratio expression (e.g. '1:2' amd '2:4' would be considered equivalent, but not equal). - message IsEquivalentSpec { + message IsEquivalentSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified ratio expression to match against the user's answer. - RatioExpression input = 1; + RatioExpressionDto input = 1; } // Represents a rule spec for checking whether an answer has a creator-specified number of // terms. - message HasNumberOfTermsEqualToSpec { + message HasNumberOfTermsEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified number of terms to match against the user's answer. @@ -1089,7 +1089,7 @@ message RatioExpressionInputInstance { // Represents a rule spec for checking whether an answer has a creator-specified term value at a // creator-specified term position within the answer. - message HasSpecificTermEqualToSpec { + message HasSpecificTermEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // Corresponds to the creator-specified term index to match against the user's answer. @@ -1102,75 +1102,75 @@ message RatioExpressionInputInstance { } } -message AlgebraicExpressionInputInstance { +message AlgebraicExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; - Outcome default_outcome = 2; + OutcomeDto default_outcome = 2; - repeated Hint hints = 3; + repeated HintDto hints = 3; - repeated AnswerGroup answer_groups = 4; + repeated AnswerGroupDto answer_groups = 4; - Solution solution = 5; + SolutionDto solution = 5; - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; repeated string value = 1; } - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; oneof rule_type { - MatchesExactlyWithSpec matches_exactly_with = 1; + MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpec contains_some_of = 3; + ContainsSomeOfSpecDto contains_some_of = 3; - OmitsSomeOfSpec omits_some_of = 4; + OmitsSomeOfSpecDto omits_some_of = 4; - MatchesWithGeneralFormSpec matches_with_general_form = 5; + MatchesWithGeneralFormSpecDto matches_with_general_form = 5; } - message MatchesExactlyWithSpec { + message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message IsEquivalentToSpec { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message ContainsSomeOfSpec { + message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message OmitsSomeOfSpec { + message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message MatchesWithGeneralFormSpec { + message MatchesWithGeneralFormSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; @@ -1179,62 +1179,62 @@ message AlgebraicExpressionInputInstance { } } - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. string correct_answer = 2; } } -message MathEquationInputInstance { +message MathEquationInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; - Outcome default_outcome = 2; + OutcomeDto default_outcome = 2; - repeated Hint hints = 3; + repeated HintDto hints = 3; - repeated AnswerGroup answer_groups = 4; + repeated AnswerGroupDto answer_groups = 4; - Solution solution = 5; + SolutionDto solution = 5; - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; repeated string value = 1; } - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; oneof rule_type { - MatchesExactlyWithSpec matches_exactly_with = 1; + MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpec contains_some_of = 3; + ContainsSomeOfSpecDto contains_some_of = 3; - OmitsSomeOfSpec omits_some_of = 4; + OmitsSomeOfSpecDto omits_some_of = 4; - MatchesWithGeneralFormSpec matches_with_general_form = 5; + MatchesWithGeneralFormSpecDto matches_with_general_form = 5; } - message MatchesExactlyWithSpec { + message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; @@ -1242,13 +1242,13 @@ message MathEquationInputInstance { string positionOfTerms = 2; } - message IsEquivalentToSpec { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message ContainsSomeOfSpec { + message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; @@ -1256,7 +1256,7 @@ message MathEquationInputInstance { string positionOfTerms = 2; } - message OmitsSomeOfSpec { + message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; @@ -1264,7 +1264,7 @@ message MathEquationInputInstance { string positionOfTerms = 2; } - message MatchesWithGeneralFormSpec { + message MatchesWithGeneralFormSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string input = 1; @@ -1273,144 +1273,144 @@ message MathEquationInputInstance { } } - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. string correct_answer = 2; } } -message NumericExpressionInputInstance { +message NumericExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - CustomizationArgs customization_args = 1; + CustomizationArgsDto customization_args = 1; - Outcome default_outcome = 2; + OutcomeDto default_outcome = 2; - repeated Hint hints = 3; + repeated HintDto hints = 3; - repeated AnswerGroup answer_groups = 4; + repeated AnswerGroupDto answer_groups = 4; - Solution solution = 5; + SolutionDto solution = 5; - message CustomizationArgs { + message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - SubtitledText placeholder = 1; + SubtitledTextDto placeholder = 1; } - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; oneof rule_type { - MatchesExactlyWithSpec matches_exactly_with = 1; + MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpec contains_some_of = 3; + ContainsSomeOfSpecDto contains_some_of = 3; - OmitsSomeOfSpec omits_some_of = 4; + OmitsSomeOfSpecDto omits_some_of = 4; } - message MatchesExactlyWithSpec { + message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message IsEquivalentToSpec { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message ContainsSomeOfSpec { + message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } - message OmitsSomeOfSpec { + message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string inputString = 1; } } - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. string correct_answer = 2; } } -message NumberWithUnitsInstance { +message NumberWithUnitsInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - Outcome default_outcome = 1; + OutcomeDto default_outcome = 1; - repeated AnswerGroup answer_groups = 2; + repeated AnswerGroupDto answer_groups = 2; - Solution solution = 3; + SolutionDto solution = 3; - message AnswerGroup { + message AnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the answer group. - BaseAnswerGroup base_answer_group = 1; + BaseAnswerGroupDto base_answer_group = 1; // The list of all rules to match for this answer group. - repeated RuleSpec rule_specs = 2; + repeated RuleSpecDto rule_specs = 2; } - message RuleSpec { + message RuleSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; oneof rule_type { - IsEqualToSpec is_equal_to = 1; + IsEqualToSpecDto is_equal_to = 1; - IsEquivalentToSpec is_equivalent_to = 2; + IsEquivalentToSpecDto is_equivalent_to = 2; } - message IsEqualToSpec { + message IsEqualToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - Fraction input = 1; + FractionDto input = 1; } - message IsEquivalentToSpec { + message IsEquivalentToSpecDtoc { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - Fraction input = 1; + FractionDto input = 1; } } - message Solution { + message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The base properties of the solution. - BaseSolution base_solution = 1; + BaseSolutionDto base_solution = 1; // The correct answer for this interaction that should be shown to the user. - Fraction correct_answer = 2; + FractionDto correct_answer = 2; } } @@ -1420,7 +1420,7 @@ message NumberWithUnitsInstance { // - Has a default outcome: no (N/A since there's no state routing after this state; it's terminal) // - Has support for showing hints: no // - Has support for showing a solution: no -message EndExplorationInstance { +message EndExplorationInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // No answers can be submitted to the end exploration interaction, so there are neither answer @@ -1431,18 +1431,18 @@ message EndExplorationInstance { // Represents the base structure for an answer group (that is, the group of fields common among all // interaction answer groups). -message BaseAnswerGroup { +message BaseAnswerGroupDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The outcome details for how the platform should response to an answer matched to this group. - Outcome outcome = 1; + OutcomeDto outcome = 1; // The misconception (if any) associated with answers matched to this group. - Misconception tagged_skill_misconception = 2; + MisconceptionDto tagged_skill_misconception = 2; } // Represents the response the platform should provide for a particular answer. -message Outcome { +message OutcomeDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The name of the state to which the user should next be navigated (which may be the same as the @@ -1450,7 +1450,7 @@ message Outcome { string destination_state = 1; // The textual feedback, if any, to show the user based on their response. - SubtitledText feedback = 2; + SubtitledTextDto feedback = 2; // Whether the answer matched to this outcome should be considered 'correct' (which may lead to // different platform behavior, such as showing a 'correct' banner). Note that some correct @@ -1462,24 +1462,24 @@ message Outcome { // Represents a hint that may be shown to the learner to help them get unstuck (in cases when the // platform detects that the learner may be having difficulty proceeding in a lesson or training // session). -message Hint { +message HintDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The main content of the hint to show the user. - SubtitledText hint_content = 1; + SubtitledTextDto hint_content = 1; } // Represents the base structure for a solution (that is, the group of fields common among all // interaction solutions). -message BaseSolution { +message BaseSolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The explanation of the solution to show the user. - SubtitledText explanation = 1; + SubtitledTextDto explanation = 1; } // Represents a single misconception of a particular skill. -message Misconception { +message MisconceptionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; // The ID of the skill that the user is likely misunderstanding. diff --git a/org/oppia/proto/v1/structure/topic_summary.proto b/org/oppia/proto/v1/structure/topic_summary.proto index cb0baa9..0612f0e 100644 --- a/org/oppia/proto/v1/structure/topic_summary.proto +++ b/org/oppia/proto/v1/structure/topic_summary.proto @@ -18,7 +18,7 @@ option java_multiple_files = true; // Topics organize 'skills' (i.e. granular units of learning) into groups called 'subtopics' which // have corresponding revision cards that learners may use to get a high-level refresher of the // corresponding skills. -message DownloadableTopicSummary { +message DownloadableTopicSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The version defining the internal structure of this message. @@ -34,13 +34,13 @@ message DownloadableTopicSummary { string description = 4; // The list of stories available to play in the topic corresponding to this sumamry. - repeated StorySummary story_summaries = 5; + repeated StorySummaryDto story_summaries = 5; // The list of subtopics available in the topic corresponding to this sumamry. - repeated SubtopicSummary subtopic_summaries = 6; + repeated SubtopicSummaryDto subtopic_summaries = 6; // The thumbnail image corresponding to this topic. - Thumbnail thumbnail = 7; + ThumbnailDto thumbnail = 7; // The version of this topic's contents. uint32 content_version = 8; @@ -49,7 +49,7 @@ message DownloadableTopicSummary { // Represents the summary of a story that can be played within a particular topic. Stories aim to // teach all of the skills covered by a topic (as defined by the topic's subtopics) via a linear // pathway of 'chapters' (which correspond to explorations). -message StorySummary { +message StorySummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The ID of the story. @@ -62,10 +62,10 @@ message StorySummary { string description = 3; // The thumbnail image of the story. - Thumbnail thumbnail = 4; + ThumbnailDto thumbnail = 4; // The summaries of all chapters in this story. - repeated ChapterSummary chapters = 5; + repeated ChapterSummaryDto chapters = 5; // The version of this story's contents. uint32 content_version = 6; @@ -73,11 +73,11 @@ message StorySummary { // Represents the summary of a single chapter within a story of a topic. Each chapter corresponds to // a single exploration (see Exploration's documentation for more details). -message ChapterSummary { +message ChapterSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The thumbnail image for this chapter. - Thumbnail thumbnail = 1; + ThumbnailDto thumbnail = 1; // The human-radable title of the chapter. This is expected to be in English, and is expected to // exactly match the title of the exploration associated to this chapter. @@ -93,21 +93,21 @@ message ChapterSummary { // Represents the summary of a subtopic (that is, a group of skills logically organized within a // topic). -message SubtopicSummary { +message SubtopicSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The index of the subtopic (within its correspnoding topic). uint32 index = 1; // The list of all skills grouped by this subtopic. - repeated SkillSummary skill_summaries = 2; + repeated SkillSummaryDto skill_summaries = 2; // The version of this subtopic's contents. uint32 content_version = 3; } // Represents the summary of a skill (see DownloadableTopicSummary for context on skills). -message SkillSummary { +message SkillSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; // The ID of the skill. From 458d489b212a79e11cefa9b0254572e664db220d Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Thu, 9 Dec 2021 07:07:24 +0530 Subject: [PATCH 32/51] nit fixes --- org/oppia/proto/v1/structure/state.proto | 104 ++++++----------------- 1 file changed, 28 insertions(+), 76 deletions(-) diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index 3ed3265..1b0088d 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -100,11 +100,9 @@ message InteractionInstanceDto { NumericExpressionInputInstanceDto numeric_expression_input = 12; - NumberWithUnitsInstanceDto number_with_units = 13; - // An interaction that represents the end of an exploration and takes no direct user input other // than navigating away from the exploration. This is not used in question play sessions. - EndExplorationInstanceDto end_exploration = 14; + EndExplorationInstanceDto end_exploration = 13; } } @@ -1118,7 +1116,9 @@ message AlgebraicExpressionInputInstanceDto { message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - repeated string value = 1; + repeated string custom_osk_letters = 1; + + bool use_fraction_for_division = 2; } message AnswerGroupDto { @@ -1149,33 +1149,33 @@ message AlgebraicExpressionInputInstanceDto { message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string algebraic_expression = 1; } message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string algebraic_expression = 1; } message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string algebraic_expression = 1; } message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string algebraic_expression = 1; } message MatchesWithGeneralFormSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string algebraic_expression = 1; - repeated string list = 2; + repeated string set_of_algebraic_identifier = 2; } } @@ -1206,7 +1206,9 @@ message MathEquationInputInstanceDto { message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - repeated string value = 1; + repeated string custom_osk_letters = 1; + + bool use_fraction_for_division = 2; } message AnswerGroupDto { @@ -1237,39 +1239,39 @@ message MathEquationInputInstanceDto { message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string math_equation = 1; - string positionOfTerms = 2; + string position_of_terms = 2; } message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string math_equation = 1; } message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string math_equation = 1; - string positionOfTerms = 2; + string position_of_terms = 2; } message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string math_equation = 1; - string positionOfTerms = 2; + string position_of_terms = 2; } message MatchesWithGeneralFormSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string input = 1; + string math_equation = 1; - repeated string list = 2; + repeated string set_of_algebraic_identifier = 2; } } @@ -1301,6 +1303,8 @@ message NumericExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; SubtitledTextDto placeholder = 1; + + bool use_fraction_for_division = 2; } message AnswerGroupDto { @@ -1329,25 +1333,25 @@ message NumericExpressionInputInstanceDto { message MatchesExactlyWithSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string numeric_expression = 1; } message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string numeric_expression = 1; } message ContainsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string numeric_expression = 1; } message OmitsSomeOfSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string inputString = 1; + string numeric_expression = 1; } } @@ -1362,58 +1366,6 @@ message NumericExpressionInputInstanceDto { } } -message NumberWithUnitsInstanceDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - OutcomeDto default_outcome = 1; - - repeated AnswerGroupDto answer_groups = 2; - - SolutionDto solution = 3; - - message AnswerGroupDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - // The base properties of the answer group. - BaseAnswerGroupDto base_answer_group = 1; - - // The list of all rules to match for this answer group. - repeated RuleSpecDto rule_specs = 2; - } - - message RuleSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - oneof rule_type { - IsEqualToSpecDto is_equal_to = 1; - - IsEquivalentToSpecDto is_equivalent_to = 2; - } - - message IsEqualToSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - FractionDto input = 1; - } - - message IsEquivalentToSpecDtoc { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - FractionDto input = 1; - } - } - - message SolutionDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - // The base properties of the solution. - BaseSolutionDto base_solution = 1; - - // The correct answer for this interaction that should be shown to the user. - FractionDto correct_answer = 2; - } -} - // Represents an interaction where the user has reached the end of the exploration, and has the // choice to navigate away from it. Details: // - Answer type: none (N/A since no answers are submitted for this interaction) From 0250c6947fc93614c48a2b07ad40ee48df7ceb23 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Thu, 9 Dec 2021 08:52:55 +0530 Subject: [PATCH 33/51] nit fixes --- org/oppia/proto/v1/api/android.proto | 68 ++++++++++++++-------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 842e751..3dac142 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -25,7 +25,7 @@ option java_multiple_files = true; // experience, the backend won't provide the client with topics or topic updates that aren't fully // localized to the languages expected by the client. // TODO(#5): Update the API to properly account for written translation packs. -message TopicListRequest { +message TopicListRequestDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. Note that the response may be @@ -35,11 +35,11 @@ message TopicListRequest { org.oppia.proto.v1.versions.TopicListRequestResponseProtoVersion proto_version = 1; // Details about the client that is making the request. - AndroidClientContext client_context = 2; + AndroidClientContextDto client_context = 2; // Details about the latest proto versions that this client can support. The server is expected to // only provide structures that exactly match the proto versions provided. - ClientCompatibilityContext compatibility_context = 3; + ClientCompatibilityContextDto compatibility_context = 3; // The current structures that are downloaded by the local client. Note that this must be a // comprehensive list of downloaded structures in order to leverage certain consistency guarantees @@ -50,13 +50,13 @@ message TopicListRequest { // Note also that all returned structures are expected to be localized to English by default with // optional additional language localizations available (as limited by the languages proto // version which denotes which languages are currently supported by the API). - repeated VersionedStructureDetails current_downloads_context = 4; + repeated VersionedStructureDetailsDto current_downloads_context = 4; } // TODO: add support for upcoming topics, for the topic graph ordering, and for topics that can't be downloaded/updated (to provide notices to the user). // The expected response from the server when provided with a TopicListRequest. -message TopicListResponse { +message TopicListResponseDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. This is expected to match the @@ -68,30 +68,30 @@ message TopicListResponse { // compatible with the local client, and topics that are marked as up-to-date are guaranteed to // be at the latest compatible version for the local client. Clients are also expected to lean on // existing local resources for topics that aren't yet downloaded. - repeated AvailableTopic available_topics = 2; + repeated AvailableTopicDto available_topics = 2; // A topic that's available to & compatible with the local client. - message AvailableTopic { + message AvailableTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The nature of the topic's availability. oneof availability_type { // Indicates a topic that's not yet downloaded by the local client, but is available to be // downloaded. - DownloadableTopic downloadable_topic = 1; + DownloadableTopicDto downloadable_topic = 1; // Indicates a topic that's downloaded by the local client, but has a compatible update. - UpdatableTopic updatable_topic = 2; + UpdatableTopicDto updatable_topic = 2; // Indicates a topic that's both downloaded by the local client & full up-to-date. This mainly // serves as a lightweight indicator to ensure that the server & client are properly in-sync // with the state of the local client. - UpToDateTopic up_to_date_topic = 3; + UpToDateTopicDto up_to_date_topic = 3; } } // Represents a topic that's available to download and is not yet downloaded by the local client. - message DownloadableTopic { + message DownloadableTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The ID of the topic that's available to newly download. This is expected to be used to @@ -103,7 +103,7 @@ message TopicListResponse { // The full summary for the current topic. Note that this will be absent if the local client // already has the latest summary downloaded as indicated by its download state context. - org.oppia.proto.v1.structure.DownloadableTopicSummary topic_summary = 2; + org.oppia.proto.v1.structure.DownloadableTopicSummaryDto topic_summary = 2; // The size, in bytes, needed to download the topic. uint32 download_size_bytes = 3; @@ -113,7 +113,7 @@ message TopicListResponse { // summary when displaying this topic, and not update it until the user requests to download the // topic. Future iterations of this API could include a preview summary here for clients to // provide context on the changes to the topic to help inform users. - message UpdatableTopic { + message UpdatableTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The ID of the topic that's available to be updated. This is expected to correspond to an @@ -134,11 +134,11 @@ message TopicListResponse { // an incremental update to minimize the download work & bandwidth needed by the local client. // update_size_bytes will reflect the data determined by the server to be needed to update the // topic. - repeated VersionedStructureDetails updated_structures = 4; + repeated VersionedStructureDetailsDto updated_structures = 4; } // Represents a topic that's been downloaded by the local client and is fully up-to-date. - message UpToDateTopic { + message UpToDateTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The ID of the topic that the server believes the local client has downloaded. In the event @@ -156,14 +156,14 @@ message TopicListResponse { // max payload size, and multiple requests can be set in parallel and at any time. Together, this // enables pagination-based retrieval and download pausing/restarting in clients, if either feature // is needed by the client. -message TopicContentRequest { +message TopicContentRequestDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. org.oppia.proto.v1.versions.TopicContentRequestResponseProtoVersion proto_version = 1; // Details about the client that is making the request. - AndroidClientContext client_context = 2; + AndroidClientContextDto client_context = 2; // Specific structure identifiers that should be fetched, preferably in the order of the list. // Note that the server only aims to prioritize earlier items in the list, but does not guarantee @@ -173,7 +173,7 @@ message TopicContentRequest { // is expected to make this determination based on the structure content & proto versions received // from the topic list API. Finally, duplicates will be ignored to avoid repeating the same data // multiple times. - repeated DownloadRequestStructureIdentifier identifiers = 3; + repeated DownloadRequestStructureIdentifierDto identifiers = 3; // The maximum payload size, in bytes, that the server should furnish as a single download // operation. This is only a request, and may not be honoured by the server (which will only @@ -184,7 +184,7 @@ message TopicContentRequest { } // The expected response from the server when provided with a TopicContentRequest. -message TopicContentResponse { +message TopicContentResponseDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The common proto version defining this request/response pair. @@ -194,17 +194,17 @@ message TopicContentResponse { // relatively in the same order as the identifiers in the request, but some items may be missing // (see the request's documentation for details). Note also that these will never include external // assets such as voiceovers or images--those always must be downloaded separately. - repeated DownloadResult download_results = 2; + repeated DownloadResultDto download_results = 2; // The result of downloading a specific structure. This may either contain the result of the // download, or an indication that the download was skipped and roughly why. The potential results // correspond to the download requests that can be made per DownloadRequestStructureIdentifier. - message DownloadResult { + message DownloadResultDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The entity type and ID corresponding to this download. This is guaranteed to exactly match at // least one of the original identifiers in the request. - DownloadRequestStructureIdentifier identifier = 1; + DownloadRequestStructureIdentifierDto identifier = 1; // The type/nature of the download result (see fields for specifics). oneof result_type { @@ -224,27 +224,27 @@ message TopicContentResponse { bool skipped_from_failure = 3; // The result is a requested topic summary. - org.oppia.proto.v1.structure.DownloadableTopicSummary topic_summary = 4; + org.oppia.proto.v1.structure.DownloadableTopicSummaryDto topic_summary = 4; // The result is a requested revision card. - org.oppia.proto.v1.structure.RevisionCard revision_card = 5; + org.oppia.proto.v1.structure.RevisionCardDto revision_card = 5; // The result is a requested concept card. - org.oppia.proto.v1.structure.ConceptCard concept_card = 6; + org.oppia.proto.v1.structure.ConceptCardDto concept_card = 6; // The result is a requested exploration. - org.oppia.proto.v1.structure.Exploration exploration = 7; + org.oppia.proto.v1.structure.ExplorationDto exploration = 7; // The result is a requested list of question IDs. QuestionIdList question_id_list = 8; // The result is a requested question. - org.oppia.proto.v1.structure.Question question = 9; + org.oppia.proto.v1.structure.QuestionDto question = 9; } } // A list of question IDs that directly correspond to a particular skill ID. - message QuestionIdList { + message QuestionIdListDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The list of question IDs that correspond to a particular skill ID. @@ -256,7 +256,7 @@ message TopicContentResponse { // includes metadata to help the backend understand the specific client that's connecting (generally // for enabling certain platform parameters, checking for app deprecation, adjusting response // protocols if necessary, and for telemetry). -message AndroidClientContext { +message AndroidClientContextDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = UNVERSIONED_API_PROTO; // The app version name corresponding to the locally installed Android client. For more @@ -273,7 +273,7 @@ message AndroidClientContext { // message, but it's permitted to send requests using any valid proto version for the request // structure. The backend is expected to always structure responses accordingly to the requested // versions provided here. -message ClientCompatibilityContext { +message ClientCompatibilityContextDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The latest proto version for topic list responses that the client can support. @@ -318,7 +318,7 @@ message ClientCompatibilityContext { // actually tied to any particular topics, and can be used across multiple topics. However, they are // downloaded with the first topic that references them, and shouldn't be re-downloaded in // subsequent topics (the backend makes guarantees to ensure that structures are never repeated). -message VersionedStructureDetails { +message VersionedStructureDetailsDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; // The backend-tracked and creator-affected content version of the structure. This is the primary @@ -335,7 +335,7 @@ message VersionedStructureDetails { string topic_summary_id = 3; // Indicates that these details correspond to a revision card, as specified by its ID structure. - org.oppia.proto.v1.structure.SubtopicId revision_card_id = 4; + org.oppia.proto.v1.structure.SubtopicIdDto revision_card_id = 4; // Indicates that these details correspond to a concept card, as specified by its skill ID. string concept_card_id = 5; @@ -360,7 +360,7 @@ message VersionedStructureDetails { // // Note that there is a special caveat on the "global-ness" of the identifiers reference here. See // VersionedStructureDetails for more details as it shares the same caveat. -message DownloadRequestStructureIdentifier { +message DownloadRequestStructureIdentifierDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_CONTENT_REQUEST_RESPONSE_PROTO_VERSION; // The content (creator-affected) version of the request. See the similar field in @@ -373,7 +373,7 @@ message DownloadRequestStructureIdentifier { string topic_summary_id = 2; // Indicates that a revision card ("subtopic") should be downloaded, as specified by its ID. - org.oppia.proto.v1.structure.SubtopicId revision_card_id = 3; + org.oppia.proto.v1.structure.SubtopicIdDto revision_card_id = 3; // Indicates that a concept card should be downloaded, as specified by its skill ID. string concept_card_id = 4; From 1b3ef9efcbeb5635222e947a76ba8b1e2517e5f2 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 10 Dec 2021 07:39:31 +0530 Subject: [PATCH 34/51] nit fixes --- org/oppia/proto/v1/api/android.proto | 2 +- org/oppia/proto/v1/structure/topic_summary.proto | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 3dac142..4d1830e 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -236,7 +236,7 @@ message TopicContentResponseDto { org.oppia.proto.v1.structure.ExplorationDto exploration = 7; // The result is a requested list of question IDs. - QuestionIdList question_id_list = 8; + QuestionIdListDto question_id_list = 8; // The result is a requested question. org.oppia.proto.v1.structure.QuestionDto question = 9; diff --git a/org/oppia/proto/v1/structure/topic_summary.proto b/org/oppia/proto/v1/structure/topic_summary.proto index 0612f0e..0760ce5 100644 --- a/org/oppia/proto/v1/structure/topic_summary.proto +++ b/org/oppia/proto/v1/structure/topic_summary.proto @@ -106,7 +106,7 @@ message SubtopicSummaryDto { uint32 content_version = 3; } -// Represents the summary of a skill (see DownloadableTopicSummary for context on skills). +// Represents the summary of a skill (see DownloadableTopicSummaryDto for context on skills). message SkillSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; From bb559ea831507c8c8e24f9b5214a83651a7c7332 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Fri, 10 Dec 2021 18:52:26 +0530 Subject: [PATCH 35/51] few doc added --- org/oppia/proto/v1/structure/state.proto | 47 +++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index 1b0088d..c3fb3c5 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -94,10 +94,13 @@ message InteractionInstanceDto { // An interaction for inputting ratios. RatioExpressionInputInstanceDto ratio_expression_input = 9; + // An interaction for inputting algebric expressions. AlgebraicExpressionInputInstanceDto algebraic_expression_input = 10; - MathEquationInputInstanceDto MathEquationInput = 11; + // An interaction for inputting math equations. + MathEquationInputInstanceDto math_equation_input = 11; + // An interaction for inputting numeric equations. NumericExpressionInputInstanceDto numeric_expression_input = 12; // An interaction that represents the end of an exploration and takes no direct user input other @@ -1100,19 +1103,31 @@ message RatioExpressionInputInstanceDto { } } +// Represents an interaction where the user can input the algebric expressions. Details: +// - Answer type: normalized string (protobuf type: string) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message AlgebraicExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // The customization arguments for this interaction. CustomizationArgsDto customization_args = 1; + // The default outcome for this interaction. OutcomeDto default_outcome = 2; + // The hints corresponding to this interaction. repeated HintDto hints = 3; + // The answer groups for this interaction. repeated AnswerGroupDto answer_groups = 4; + // The solution corresponding to this interaction. SolutionDto solution = 5; + // Represents the customization arguments available for instances of the algebric expression input + // interaction. message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -1179,6 +1194,8 @@ message AlgebraicExpressionInputInstanceDto { } } + // Represents the specific solution available to instances of the algebric expression input + // interaction. message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -1190,19 +1207,31 @@ message AlgebraicExpressionInputInstanceDto { } } +// Represents an interaction where the user can input the math equaltions. Details: +// - Answer type: normalized string (protobuf type: string) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message MathEquationInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // The customization arguments for this interaction. CustomizationArgsDto customization_args = 1; + // The default outcome for this interaction. OutcomeDto default_outcome = 2; + // The hints corresponding to this interaction. repeated HintDto hints = 3; + // The answer groups for this interaction. repeated AnswerGroupDto answer_groups = 4; + // The solution corresponding to this interaction. SolutionDto solution = 5; + // Represents the customization arguments available for instances of the math equation input + // interaction. message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -1275,6 +1304,8 @@ message MathEquationInputInstanceDto { } } + // Represents the specific solution available to instances of the math equation input + // interaction. message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -1286,19 +1317,31 @@ message MathEquationInputInstanceDto { } } +// Represents an interaction where the user can input the numeric expressions. Details: +// - Answer type: normalized string (protobuf type: string) +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes message NumericExpressionInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + // The customization arguments for this interaction. CustomizationArgsDto customization_args = 1; + // The default outcome for this interaction. OutcomeDto default_outcome = 2; + // The hints corresponding to this interaction. repeated HintDto hints = 3; + // The answer groups for this interaction. repeated AnswerGroupDto answer_groups = 4; + // The solution corresponding to this interaction. SolutionDto solution = 5; + // Represents the customization arguments available for instances of the numeric expression input + // interaction. message CustomizationArgsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; @@ -1355,6 +1398,8 @@ message NumericExpressionInputInstanceDto { } } + // Represents the specific solution available to instances of the numeric expression input + // interaction. message SolutionDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; From 886e1fca30b69f604cbc327c07e913edb2211792 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Mon, 24 Jan 2022 09:27:31 +0530 Subject: [PATCH 36/51] update math interaction rule and added MatchesUpToTrivialManipulationsSpecDto --- org/oppia/proto/v1/structure/state.proto | 62 +++--------------------- 1 file changed, 8 insertions(+), 54 deletions(-) diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index c3fb3c5..c2c2915 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -1154,11 +1154,7 @@ message AlgebraicExpressionInputInstanceDto { IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpecDto contains_some_of = 3; - - OmitsSomeOfSpecDto omits_some_of = 4; - - MatchesWithGeneralFormSpecDto matches_with_general_form = 5; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; } message MatchesExactlyWithSpecDto { @@ -1173,24 +1169,10 @@ message AlgebraicExpressionInputInstanceDto { string algebraic_expression = 1; } - message ContainsSomeOfSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - string algebraic_expression = 1; - } - - message OmitsSomeOfSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - string algebraic_expression = 1; - } - - message MatchesWithGeneralFormSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string algebraic_expression = 1; - - repeated string set_of_algebraic_identifier = 2; } } @@ -1258,11 +1240,7 @@ message MathEquationInputInstanceDto { IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpecDto contains_some_of = 3; - - OmitsSomeOfSpecDto omits_some_of = 4; - - MatchesWithGeneralFormSpecDto matches_with_general_form = 5; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; } message MatchesExactlyWithSpecDto { @@ -1279,28 +1257,12 @@ message MathEquationInputInstanceDto { string math_equation = 1; } - message ContainsSomeOfSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - string math_equation = 1; - - string position_of_terms = 2; - } - - message OmitsSomeOfSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - string math_equation = 1; - - string position_of_terms = 2; - } - - message MatchesWithGeneralFormSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string math_equation = 1; + string lhs_equation = 1; - repeated string set_of_algebraic_identifier = 2; + string rhs_equation = 2; } } @@ -1368,9 +1330,7 @@ message NumericExpressionInputInstanceDto { IsEquivalentToSpecDto is_equivalent_to = 2; - ContainsSomeOfSpecDto contains_some_of = 3; - - OmitsSomeOfSpecDto omits_some_of = 4; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; } message MatchesExactlyWithSpecDto { @@ -1385,13 +1345,7 @@ message NumericExpressionInputInstanceDto { string numeric_expression = 1; } - message ContainsSomeOfSpecDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - - string numeric_expression = 1; - } - - message OmitsSomeOfSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string numeric_expression = 1; From 8f3cde883c31785438e80656a5b6bb26bd01b6a1 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Tue, 25 Jan 2022 10:23:00 +0530 Subject: [PATCH 37/51] nit fix for math rules --- org/oppia/proto/v1/structure/state.proto | 34 +++++++++++------------- 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index c2c2915..e9468d2 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -1152,9 +1152,9 @@ message AlgebraicExpressionInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpecDto is_equivalent_to = 2; - - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + + IsEquivalentToSpecDto is_equivalent_to = 3; } message MatchesExactlyWithSpecDto { @@ -1163,13 +1163,13 @@ message AlgebraicExpressionInputInstanceDto { string algebraic_expression = 1; } - message IsEquivalentToSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string algebraic_expression = 1; } - message MatchesUpToTrivialManipulationsSpecDto { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string algebraic_expression = 1; @@ -1238,9 +1238,9 @@ message MathEquationInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpecDto is_equivalent_to = 2; - - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + + IsEquivalentToSpecDto is_equivalent_to = 3; } message MatchesExactlyWithSpecDto { @@ -1251,18 +1251,16 @@ message MathEquationInputInstanceDto { string position_of_terms = 2; } - message IsEquivalentToSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string math_equation = 1; } - message MatchesUpToTrivialManipulationsSpecDto { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; - string lhs_equation = 1; - - string rhs_equation = 2; + string math_equation = 1; } } @@ -1328,9 +1326,9 @@ message NumericExpressionInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - IsEquivalentToSpecDto is_equivalent_to = 2; - - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 3; + MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + + IsEquivalentToSpecDto is_equivalent_to = 3; } message MatchesExactlyWithSpecDto { @@ -1339,13 +1337,13 @@ message NumericExpressionInputInstanceDto { string numeric_expression = 1; } - message IsEquivalentToSpecDto { + message MatchesUpToTrivialManipulationsSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string numeric_expression = 1; } - message MatchesUpToTrivialManipulationsSpecDto { + message IsEquivalentToSpecDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string numeric_expression = 1; From 4ae1907d41ef3219ebd9b2513b6e2d5adf05518b Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Thu, 10 Feb 2022 17:54:39 +0530 Subject: [PATCH 38/51] updated RevisionCardDto --- org/oppia/proto/v1/structure/revision_card.proto | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/org/oppia/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto index fe9e764..7ac90ab 100644 --- a/org/oppia/proto/v1/structure/revision_card.proto +++ b/org/oppia/proto/v1/structure/revision_card.proto @@ -45,7 +45,7 @@ message RevisionCardDto { } // Represents the identifier for a subtopic (which are tightly tied to specific topics). -message SubtopicIdDto { +message SubtopicPageIdDto { // This proto message type is shared among multiple protos, so it has no direct migration pathway. // Changes here should be carefully done in a way that does not break compatibility or assumptions // across all relevant proto versions, or the proto should be duplicated according to whichever @@ -55,6 +55,6 @@ message SubtopicIdDto { // The ID of the topic that contains this subtopic. string topic_id = 1; - // The index of this subtopic within its topic. - uint32 index = 2; + // The ID of the subtopic. + uint32 subtopic_id = 2; } From bc78dd9b595569a12a2a8991d429d00f1ed3bd77 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Thu, 10 Feb 2022 18:07:05 +0530 Subject: [PATCH 39/51] nit fix revision card --- org/oppia/proto/v1/api/android.proto | 4 ++-- org/oppia/proto/v1/structure/revision_card.proto | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 4d1830e..83ea81b 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -335,7 +335,7 @@ message VersionedStructureDetailsDto { string topic_summary_id = 3; // Indicates that these details correspond to a revision card, as specified by its ID structure. - org.oppia.proto.v1.structure.SubtopicIdDto revision_card_id = 4; + org.oppia.proto.v1.structure.SubtopicPageIdDto revision_card_id = 4; // Indicates that these details correspond to a concept card, as specified by its skill ID. string concept_card_id = 5; @@ -373,7 +373,7 @@ message DownloadRequestStructureIdentifierDto { string topic_summary_id = 2; // Indicates that a revision card ("subtopic") should be downloaded, as specified by its ID. - org.oppia.proto.v1.structure.SubtopicIdDto revision_card_id = 3; + org.oppia.proto.v1.structure.SubtopicPageIdDto revision_card_id = 3; // Indicates that a concept card should be downloaded, as specified by its skill ID. string concept_card_id = 4; diff --git a/org/oppia/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto index 7ac90ab..2227bab 100644 --- a/org/oppia/proto/v1/structure/revision_card.proto +++ b/org/oppia/proto/v1/structure/revision_card.proto @@ -23,7 +23,7 @@ message RevisionCardDto { org.oppia.proto.v1.versions.RevisionCardProtoVersion proto_version = 1; // The structured ID of the subtopic corresponding to this revision card. - SubtopicIdDto id = 2; + SubtopicPageIdDto id = 2; // The human-readable title of the revision card. This is expected to be in English. string title = 3; From 6c3b65a9e0bc79ea9f7db484288ed77063498ce6 Mon Sep 17 00:00:00 2001 From: anandwana001 Date: Thu, 10 Feb 2022 18:51:38 +0530 Subject: [PATCH 40/51] nit fix --- org/oppia/proto/v1/structure/revision_card.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto index 2227bab..c04e8cd 100644 --- a/org/oppia/proto/v1/structure/revision_card.proto +++ b/org/oppia/proto/v1/structure/revision_card.proto @@ -56,5 +56,5 @@ message SubtopicPageIdDto { string topic_id = 1; // The ID of the subtopic. - uint32 subtopic_id = 2; + string subtopic_id = 2; } From 58b1b7bc714ad92213b39231f9be83f79591ffd5 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Tue, 8 Mar 2022 18:34:54 -0800 Subject: [PATCH 41/51] Move repo bzl files to correct top-level location. This also removes a field that shouldn't be in one of the math equation specs. --- WORKSPACE | 4 ++-- org/oppia/proto/v1/structure/state.proto | 2 -- {org/oppia/repo => repo}/BUILD | 0 {org/oppia/repo => repo}/deps.bzl | 0 {org/oppia/repo => repo}/toolchains.bzl | 0 5 files changed, 2 insertions(+), 4 deletions(-) rename {org/oppia/repo => repo}/BUILD (100%) rename {org/oppia/repo => repo}/deps.bzl (100%) rename {org/oppia/repo => repo}/toolchains.bzl (100%) diff --git a/WORKSPACE b/WORKSPACE index 428217c..b7156f6 100644 --- a/WORKSPACE +++ b/WORKSPACE @@ -2,10 +2,10 @@ The top-level WORKSPACE definition for the Oppia proto API Bazel workspace. """ -load("//org/oppia/repo:deps.bzl", "initializeDepsForWorkspace") +load("//repo:deps.bzl", "initializeDepsForWorkspace") initializeDepsForWorkspace() -load("//org/oppia/repo:toolchains.bzl", "initializeToolchainsForWorkspace") +load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") initializeToolchainsForWorkspace() diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index e9468d2..025cf36 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -1247,8 +1247,6 @@ message MathEquationInputInstanceDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; string math_equation = 1; - - string position_of_terms = 2; } message MatchesUpToTrivialManipulationsSpecDto { diff --git a/org/oppia/repo/BUILD b/repo/BUILD similarity index 100% rename from org/oppia/repo/BUILD rename to repo/BUILD diff --git a/org/oppia/repo/deps.bzl b/repo/deps.bzl similarity index 100% rename from org/oppia/repo/deps.bzl rename to repo/deps.bzl diff --git a/org/oppia/repo/toolchains.bzl b/repo/toolchains.bzl similarity index 100% rename from org/oppia/repo/toolchains.bzl rename to repo/toolchains.bzl From 1c129b71d09d851bebda821e82bc0f70949118fd Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Thu, 14 Apr 2022 19:00:32 -0700 Subject: [PATCH 42/51] Add language support for Swahili. --- org/oppia/proto/v1/structure/languages.proto | 3 +++ 1 file changed, 3 insertions(+) diff --git a/org/oppia/proto/v1/structure/languages.proto b/org/oppia/proto/v1/structure/languages.proto index bb22cae..c1b50a1 100644 --- a/org/oppia/proto/v1/structure/languages.proto +++ b/org/oppia/proto/v1/structure/languages.proto @@ -41,6 +41,9 @@ enum LanguageType { // Corresponds to a regional Portuguese that's primarily used in Brazil. BRAZILIAN_PORTUGUESE = 5; + + // Corresponds to general Swahili (that is, not particularly regionally tied). + SWAHILI = 6; } // Represents a block of (subtitled) text. This structure is used for content strings so that they From 7f766e18a4cd25612415f8274230a46b334b583e Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 27 Feb 2023 18:17:08 -0800 Subject: [PATCH 43/51] Significant changes. Specifically: - Adds buf & buildifier support (within Bazel) as actual tests, plus fixes issues found by both. - Restricts building to Bazel 4.0.0 (since this is what Oppia Android is currently limited to). - Significantly revamps how all things localization are stored (and fully defines them for all structures). - Finishes topic list request/response support. - Changes how third-party dependencies are managed at the repository-level for cleanliness. There are still a few TODOs left to resolve, but the structures are much closer to finished as of this commit (sans addressing any existing comments on GitHub). These changes have been verified via a new asset download script being built for Oppia Android's release pipeline. --- .bazelversion | 1 + BUILD | 18 ++- defs/BUILD | 5 + defs/buf.yaml | 7 + defs/defs.bzl | 51 +++++++ org/oppia/proto/v1/api/BUILD | 13 +- org/oppia/proto/v1/api/android.proto | 142 +++++++++++++++--- org/oppia/proto/v1/structure/BUILD | 11 +- .../proto/v1/structure/concept_card.proto | 53 +++++-- .../proto/v1/structure/exploration.proto | 45 +++++- org/oppia/proto/v1/structure/image.proto | 33 ++-- org/oppia/proto/v1/structure/languages.proto | 115 +++++++------- org/oppia/proto/v1/structure/objects.proto | 18 ++- org/oppia/proto/v1/structure/question.proto | 42 +++++- .../proto/v1/structure/revision_card.proto | 54 +++++-- org/oppia/proto/v1/structure/state.proto | 22 +-- .../proto/v1/structure/topic_summary.proto | 141 +++++++++++++---- .../proto/v1/versions/{BUILD.bazel => BUILD} | 11 +- .../proto/v1/versions/api_versions.proto | 5 + .../v1/versions/structure_versions.proto | 19 ++- repo/BUILD | 4 + repo/deps.bzl | 95 +++--------- repo/toolchains.bzl | 48 ++++-- repo/versions.bzl | 56 +++++++ 24 files changed, 725 insertions(+), 284 deletions(-) create mode 100644 .bazelversion create mode 100644 defs/BUILD create mode 100644 defs/buf.yaml create mode 100644 defs/defs.bzl rename org/oppia/proto/v1/versions/{BUILD.bazel => BUILD} (52%) create mode 100644 repo/versions.bzl diff --git a/.bazelversion b/.bazelversion new file mode 100644 index 0000000..fcdb2e1 --- /dev/null +++ b/.bazelversion @@ -0,0 +1 @@ +4.0.0 diff --git a/BUILD b/BUILD index a97f945..efbe1f4 100644 --- a/BUILD +++ b/BUILD @@ -4,8 +4,10 @@ public, importable API should be defined here (and all such libraries should be nowhere else). """ -load("@rules_proto//proto:defs.bzl", "proto_library") +load("@com_github_bazelbuild_buildtools//buildifier:buildifier.bzl", "buildifier") load("@rules_java//java:defs.bzl", "java_lite_proto_library", "java_proto_library") +load("@rules_proto//proto:defs.bzl", "proto_library") +load("//defs:defs.bzl", "BUILDIFIER_LINT_WARNINGS", "define_buildifier_tests") package_group( name = "api_visibility", @@ -30,9 +32,9 @@ proto_library( name = "android_protos", visibility = ["//visibility:public"], deps = [ - "//org/oppia/proto/v1/api:android_proto", - "//org/oppia/proto/v1/structure:structure_proto", - "//org/oppia/proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/api:android_proto", + "//org/oppia/proto/v1/structure:structure_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) @@ -49,3 +51,11 @@ java_lite_proto_library( visibility = ["//visibility:public"], deps = [":android_protos"], ) + +buildifier( + name = "fix_bazel_lint_problems", + lint_mode = "fix", + lint_warnings = BUILDIFIER_LINT_WARNINGS, +) + +define_buildifier_tests() diff --git a/defs/BUILD b/defs/BUILD new file mode 100644 index 0000000..44381ab --- /dev/null +++ b/defs/BUILD @@ -0,0 +1,5 @@ +""" +Starlark macros that help ensure clean proto & Bazel dependency management. +""" + +exports_files(["buf.yaml"]) diff --git a/defs/buf.yaml b/defs/buf.yaml new file mode 100644 index 0000000..a2311f8 --- /dev/null +++ b/defs/buf.yaml @@ -0,0 +1,7 @@ +version: v1 +lint: + use: + - DEFAULT + except: + - PACKAGE_VERSION_SUFFIX + - ENUM_VALUE_PREFIX diff --git a/defs/defs.bzl b/defs/defs.bzl new file mode 100644 index 0000000..2e84a7b --- /dev/null +++ b/defs/defs.bzl @@ -0,0 +1,51 @@ +""" +Defines Starlark macros that are used to define protos and set up Bazel build directories (and +automatically define Buf & Buildifier lint tests). +""" + +load("@com_github_bazelbuild_buildtools//buildifier:buildifier.bzl", "buildifier_test") +load("@rules_buf//buf:defs.bzl", "buf_lint_test") +load("@rules_proto//proto:defs.bzl", "proto_library") + +# Configured lint warnings for Buildifier linter tests & autofixing configuration. +BUILDIFIER_LINT_WARNINGS = [ + "+out-of-order-load", + "+unsorted-dict-items", +] + +def oppia_proto_library(name, relative_parent_dir_path, **kwargs): + """ + Defines an Oppia API-compatible proto library, and a lint test with the same name ending in + "_lint_test"." + + Args: + name: str. The name of the library being defined. + relative_parent_dir_path: str. The relative directory path to the containing Bazel package. + **kwargs: additional parameters passed into proto_library. + """ + + proto_library( + name = name, + import_prefix = relative_parent_dir_path, # Make directory prefix match declared package. + strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. + **kwargs + ) + + buf_lint_test( + name = "%s_lint_test" % name, + config = "//defs:buf.yaml", + targets = [name], + ) + +def define_buildifier_tests(): + """ + Defines a Bazel lint test for this package with the name "bazel_lint_check_test". + """ + + buildifier_test( + name = "bazel_lint_check_test", + srcs = native.glob(["WORKSPACE"]) + native.glob(["BUILD"]) + native.glob(["*.bazel"]) + native.glob(["*.bzl"]), + lint_mode = "warn", + lint_warnings = BUILDIFIER_LINT_WARNINGS, + verbose = True, + ) diff --git a/org/oppia/proto/v1/api/BUILD b/org/oppia/proto/v1/api/BUILD index 39ef881..418adf6 100644 --- a/org/oppia/proto/v1/api/BUILD +++ b/org/oppia/proto/v1/api/BUILD @@ -2,16 +2,17 @@ Libraries that define endpoint API protos for interacting with Oppia's backend. """ -load("@rules_proto//proto:defs.bzl", "proto_library") +load("//defs:defs.bzl", "define_buildifier_tests", "oppia_proto_library") -proto_library( +oppia_proto_library( name = "android_proto", srcs = ["android.proto"], + relative_parent_dir_path = "org/oppia/proto/v1/api", visibility = ["//:api_visibility"], - strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. - import_prefix = "org/oppia/proto/v1/api", # Make directory prefix match declared package. deps = [ - "//org/oppia/proto/v1/structure:structure_proto", - "//org/oppia/proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/structure:structure_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) + +define_buildifier_tests() diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 83ea81b..9da82bd 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -4,6 +4,7 @@ package org.oppia.proto.v1.api; import "org/oppia/proto/v1/structure/concept_card.proto"; import "org/oppia/proto/v1/structure/exploration.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/structure/question.proto"; import "org/oppia/proto/v1/structure/revision_card.proto"; import "org/oppia/proto/v1/structure/topic_summary.proto"; @@ -24,7 +25,6 @@ option java_multiple_files = true; // Another dimension of compatibility is the list of supported languages. For an optimal user // experience, the backend won't provide the client with topics or topic updates that aren't fully // localized to the languages expected by the client. -// TODO(#5): Update the API to properly account for written translation packs. message TopicListRequestDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; @@ -46,14 +46,43 @@ message TopicListRequestDto { // by the backend, including ensuring that structures are never re-downloaded or violate the // one-version expectation (that is, only the latest compatible version of a shared cross-topic // structure is downloaded and never multiple versions of it). - // - // Note also that all returned structures are expected to be localized to English by default with - // optional additional language localizations available (as limited by the languages proto - // version which denotes which languages are currently supported by the API). repeated VersionedStructureDetailsDto current_downloads_context = 4; -} -// TODO: add support for upcoming topics, for the topic graph ordering, and for topics that can't be downloaded/updated (to provide notices to the user). + // Dictates what default localizations should be included with all topics and lessons available to + // download. Note that this will guarantee exclusion of an topics or lessons that do not have 100% + // translations of the specified language (from the client's perspective, the topic will not even + // exist except possibly in the dependency graph provided by TopicListResponseDto). + // + // It is the *client's* responsibility to not change this language across requests. This should be + // a default language indicated by the client's infrastructure, not the user (as separate + // localization packs can be downloaded by the client). The server makes no compatibility + // guarantee for subsequent requests with different languages. Different languages should be + // downloaded using a topic content request. + // + // This value is required for proper functioning of the system. The server is may fail the request + // or return a suitable default if this value is omitted. + org.oppia.proto.v1.structure.LanguageType requested_default_language = 5; + + // The list of additional languages supported by the client. This is only used for the purpose of + // localizing topic & topic substructure summaries, not downloaded content (which should use a + // topic content request, instead). The server makes no effort to remember these languages, nor + // guarantee compatibility in the returned list of topics. This list of languages is only meant to + // populate summary language data on a best-effort basis. + // + // This list may contain any languages (including the requested default language), except the + // requested default language will be ignored in this list if it's present. This list is optional + // for clients to populate if localization isn't needed. This list is *not* used to compute + // updates to language packs (as the context for those packs are defined as part of + // VersionedStructureDetailsDto). + repeated org.oppia.proto.v1.structure.LanguageType supported_additional_languages = 6; + + // The list of additional languages that require 100% translations in order to be considered + // compatible with the client. If, for example, Swahili is included in this list but a topic was + // updated and is now at 99% Swahili translations, the previous version that contained 100% will + // be provided to the client. Topics that do not have any versions with 100% Swahili translations + // would be included as future topics. + repeated org.oppia.proto.v1.structure.LanguageType required_additional_languages = 7; +} // The expected response from the server when provided with a TopicListRequest. message TopicListResponseDto { @@ -70,6 +99,9 @@ message TopicListResponseDto { // existing local resources for topics that aren't yet downloaded. repeated AvailableTopicDto available_topics = 2; + // A list of all topics that will be available to the client to install in the future. + repeated FutureTopicDto future_topics = 3; + // A topic that's available to & compatible with the local client. message AvailableTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; @@ -83,10 +115,17 @@ message TopicListResponseDto { // Indicates a topic that's downloaded by the local client, but has a compatible update. UpdatableTopicDto updatable_topic = 2; - // Indicates a topic that's both downloaded by the local client & full up-to-date. This mainly - // serves as a lightweight indicator to ensure that the server & client are properly in-sync - // with the state of the local client. + // Indicates a topic that's both downloaded by the local client & fully up-to-date. This + // mainly serves as a lightweight indicator to ensure that the server & client are properly + // in-sync with the state of the local client. This will only be sent if the client has the + // very latest version of the topic. If there's a newer version, either updatable_topic or + // not_updatable_topic will be sent. UpToDateTopicDto up_to_date_topic = 3; + + // Indicates a topic that cannot be updated due to a binary incompatibility with the local + // client. This will only be sent if there's a topic version that the client cannot download, + // and it already has the latest internally consistent representation of the topic downloaded. + NotUpdatableTopicDto not_updatable_topic = 4; } } @@ -149,6 +188,31 @@ message TopicListResponseDto { // The content version of the topic that the server believes the local client has downloaded. uint32 content_version = 2; } + + // Represents a topic that's not up-to-date, but that the app cannot install due to binary + // incompatibility. + message NotUpdatableTopicDto { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + + // The ID of the topic that the server cannot create a compatible binary representation of, for + // its latest version. + string topic_id = 1; + + // The content version of the topic that cannot be downloaded by the client. Clients can assume + // that the server has already provided the latest compatible content version. + uint32 content_version = 2; + } + + // Represents a topic that's not yet available to download (due to it not being released). + message FutureTopicDto { + option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; + + // The ID of the topic that will eventually exist, but doesn't yet. + string topic_id = 1; + + // A summary of the topic that will be later released and available to download. + org.oppia.proto.v1.structure.UpcomingTopicSummaryDto topic_summary = 2; + } } // The request made to the server to get the latest compatible content for specific topics. This @@ -240,6 +304,18 @@ message TopicContentResponseDto { // The result is a requested question. org.oppia.proto.v1.structure.QuestionDto question = 9; + + // The result is a requested revision card language pack. + org.oppia.proto.v1.structure.RevisionCardLanguagePackDto revision_card_language_pack = 10; + + // The result is a requested concept card language pack. + org.oppia.proto.v1.structure.ConceptCardLanguagePackDto concept_card_language_pack = 11; + + // The result is a requested exploration language pack. + org.oppia.proto.v1.structure.ExplorationLanguagePackDto exploration_language_pack = 12; + + // The result is a requested question language pack. + org.oppia.proto.v1.structure.QuestionLanguagePackDto question_language_pack = 13; } } @@ -304,7 +380,7 @@ message ClientCompatibilityContextDto { org.oppia.proto.v1.versions.LanguageProtosVersion language_protos_version = 9; // The latest proto version for images that the client can support. - org.oppia.proto.v1.versions.ImageProtoVersion thumbnail_proto_version = 10; + org.oppia.proto.v1.versions.ImageProtoVersion image_proto_version = 10; } // Details about a versione dstructure that's compatible with the local client. This can be used @@ -335,25 +411,41 @@ message VersionedStructureDetailsDto { string topic_summary_id = 3; // Indicates that these details correspond to a revision card, as specified by its ID structure. - org.oppia.proto.v1.structure.SubtopicPageIdDto revision_card_id = 4; + org.oppia.proto.v1.structure.LocalizedRevisionCardIdDto revision_card = 4; // Indicates that these details correspond to a concept card, as specified by its skill ID. - string concept_card_id = 5; + org.oppia.proto.v1.structure.LocalizedConceptCardIdDto concept_card = 5; // Indicates that these details correspond to a story, as specified by its ID. string story_id = 6; // Indicates that these details correspond to an exploration, as specified by its ID. - string exploration_id = 7; + org.oppia.proto.v1.structure.LocalizedExplorationIdDto exploration = 7; // Indicates that these details correspond to a question, as specified by its ID. - string question_id = 8; + org.oppia.proto.v1.structure.LocalizedQuestionIdDto question = 8; // Indicates that these details correspond to a skill, as specified by its ID. string skill_id = 9; + + // Indicates these details correspond to a revision card language pack, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedRevisionCardIdDto revision_card_language_pack = 10; + + // Indicates these details correspond to a concept card language pack, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedConceptCardIdDto concept_card_language_pack = 11; + + // Indicates these details correspond to an exploration language pack, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedExplorationIdDto exploration_language_pack = 12; + + // Indicates that these details correspond to a question language pack, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedQuestionIdDto question_language_pack = 13; } } +// TODO: Downloading topic summaries & representing topics, topic summaries, stories, and skills +// probably requires having a similar language representation as those used for language packs (so +// that language changes can trigger re-downloads). + // An identifier used to download a specific structure at a particular content version as part of // the topic content API. It's expected that the server-provided structure will utilize the provided // proto version requested by the client. @@ -373,19 +465,31 @@ message DownloadRequestStructureIdentifierDto { string topic_summary_id = 2; // Indicates that a revision card ("subtopic") should be downloaded, as specified by its ID. - org.oppia.proto.v1.structure.SubtopicPageIdDto revision_card_id = 3; + org.oppia.proto.v1.structure.LocalizedRevisionCardIdDto revision_card = 3; // Indicates that a concept card should be downloaded, as specified by its skill ID. - string concept_card_id = 4; + org.oppia.proto.v1.structure.LocalizedConceptCardIdDto concept_card = 4; // Indicates that an exploration should be downloaded, as specified by its ID. - string exploration_id = 5; + org.oppia.proto.v1.structure.LocalizedExplorationIdDto exploration = 5; // Indicates that the list of questions associated with a specific skill ID should be // downloaded, as specified by that ID. string question_list_skill_id = 6; // Indicates that a question should be downloaded, as specified by its ID. - string question_id = 7; + org.oppia.proto.v1.structure.LocalizedQuestionIdDto question = 7; + + // Indicates that a revision card language pack should be downloaded, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedRevisionCardIdDto revision_card_language_pack = 8; + + // Indicates that a concept card language pack should be downloaded, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedConceptCardIdDto concept_card_language_pack = 9; + + // Indicates that an exploration language pack should be downloaded, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedExplorationIdDto exploration_language_pack = 10; + + // Indicates that a question language pack should be downloaded, as specified by its ID. + org.oppia.proto.v1.structure.LocalizedQuestionIdDto question_language_pack = 11; } } diff --git a/org/oppia/proto/v1/structure/BUILD b/org/oppia/proto/v1/structure/BUILD index 316ff23..75e0622 100644 --- a/org/oppia/proto/v1/structure/BUILD +++ b/org/oppia/proto/v1/structure/BUILD @@ -2,9 +2,9 @@ Libraries that define core lesson structure protos. """ -load("@rules_proto//proto:defs.bzl", "proto_library") +load("//defs:defs.bzl", "define_buildifier_tests", "oppia_proto_library") -proto_library( +oppia_proto_library( name = "structure_proto", srcs = [ "concept_card.proto", @@ -17,13 +17,14 @@ proto_library( "state.proto", "topic_summary.proto", ], - strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. - import_prefix = "org/oppia/proto/v1/structure", # Make directory prefix match declared package. + relative_parent_dir_path = "org/oppia/proto/v1/structure", visibility = [ "//:api_visibility", "//:proto_impl_visibility", ], deps = [ - "//org/oppia/proto/v1/versions:versions_proto", + "//org/oppia/proto/v1/versions:versions_proto", ], ) + +define_buildifier_tests() diff --git a/org/oppia/proto/v1/structure/concept_card.proto b/org/oppia/proto/v1/structure/concept_card.proto index 6d0676b..129782c 100644 --- a/org/oppia/proto/v1/structure/concept_card.proto +++ b/org/oppia/proto/v1/structure/concept_card.proto @@ -2,7 +2,6 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; @@ -22,8 +21,8 @@ message ConceptCardDto { // The ID corresponding to the skill this concept is representing. string skill_id = 2; - // A human-readable description for the skill. This is expected to be in English. - string description = 3; + // A localizable description for the skill. + SubtitledTextDto description = 3; // The localizable explanation of the skill that is to be shown in the concept card. SubtitledTextDto explanation = 4; @@ -31,19 +30,12 @@ message ConceptCardDto { // A list of worked examples to present to the learner. repeated WorkedExampleDto worked_examples = 5; - // The recorded voiceovers for SubtitledText subfields of this concept card. - RecordedVoiceoversDto recorded_voiceovers = 6; - - // The translations of SubtitledText subfields of this concept card. - WrittenTranslationsDto written_translations = 7; - - // The list of all images that are included within SubtitledText subfields of this concept card. - // This is expected to include all references images, including in translations. - ReferencedImageListDto referenced_image_list = 8; + // The default localized text, images, and voiceovers of this concept card. + ContentLocalizationDto default_localization = 6; // The version of the contents of this concept card (which corresponds to the 'version' field for // the concept card's skill on the server). - uint32 content_version = 9; + uint32 content_version = 7; // Represents a worked example (which provides a sample question and answer for the learner to // read and learn from). @@ -57,3 +49,38 @@ message ConceptCardDto { SubtitledTextDto explanation = 2; } } + +// Represents a localized language pack corresponding to both a single concept card and a single +// language. +message ConceptCardLanguagePackDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = CONCEPT_CARD_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.ConceptCardProtoVersion proto_version = 1; + + // The ID of the pack. + LocalizedConceptCardIdDto id = 2; + + // The language-specific localized text, images, and voiceovers of this concept card. + ContentLocalizationDto localization = 3; + + // The version of the pack's contents (e.g. specific translations). + uint32 content_version = 4; +} + +// Represents the identifier for a localized concept card, either indicating the concept card's +// default language, or referencing a language pack for the concept card. +message LocalizedConceptCardIdDto { + // This proto message type is shared among multiple protos, so it has no direct migration pathway. + // Changes here should be carefully done in a way that does not break compatibility or assumptions + // across all relevant proto versions, or the proto should be duplicated according to whichever + // proto requires alterations. + option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + // The ID corresponding to the skill the concept card is representing. + string skill_id = 1; + + // The language being localized either as the default for the concept card, or provided by a + // language pack. + LanguageType language = 2; +} diff --git a/org/oppia/proto/v1/structure/exploration.proto b/org/oppia/proto/v1/structure/exploration.proto index f1b2f91..bd32d8f 100644 --- a/org/oppia/proto/v1/structure/exploration.proto +++ b/org/oppia/proto/v1/structure/exploration.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/structure/state.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; @@ -20,8 +20,8 @@ message ExplorationDto { // The ID of the exploration. string id = 2; - // The human-readable title of the exploration. This is expected to be in English. - string title = 3; + // The localizable title of the exploration. + SubtitledTextDto title = 3; // The name of the initial state of the exploration. This corresponds to keys in the 'states' // field. @@ -35,6 +35,41 @@ message ExplorationDto { // the server). uint32 content_version = 6; - // A list of all the images contained in SubtitledText subfields of this exploration. - ReferencedImageListDto referenced_image_list = 7; + // The default localized text, images, and voiceovers of this exploration. + ContentLocalizationDto default_localization = 7; +} + +// Represents a localized language pack corresponding to both a single exploration and a single +// language. +message ExplorationLanguagePackDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = EXPLORATION_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.ExplorationProtoVersion proto_version = 1; + + // The ID of the pack. + LocalizedExplorationIdDto id = 2; + + // The language-specific localized text, images, and voiceovers of this exploration. + ContentLocalizationDto localization = 3; + + // The version of the pack's contents (e.g. specific translations). + uint32 content_version = 4; +} + +// Represents the identifier for a localized exploration, either indicating the exploration's +// default language, or referencing a language pack for the exploration. +message LocalizedExplorationIdDto { + // This proto message type is shared among multiple protos, so it has no direct migration pathway. + // Changes here should be carefully done in a way that does not break compatibility or assumptions + // across all relevant proto versions, or the proto should be duplicated according to whichever + // proto requires alterations. + option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + // The ID of the exploration. + string exploration_id = 1; + + // The language being localized either as the default for the exploration, or provided by a + // language pack. + LanguageType language = 2; } diff --git a/org/oppia/proto/v1/structure/image.proto b/org/oppia/proto/v1/structure/image.proto index d1a1545..3cbf7cd 100644 --- a/org/oppia/proto/v1/structure/image.proto +++ b/org/oppia/proto/v1/structure/image.proto @@ -20,14 +20,8 @@ message ThumbnailDto { // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; - // The name of the thumbnail image file. This will never be a URL (and can always be expected to - // just be a filename). The image is stored in GCS static file storage and must be downloaded - // separately by the client. The client can expect that this image is immutable on the server. - // Further, the client can also assume that all images are one of three formats: - // - PNG (indicated with a .png extension) - // - WebP (indicated with a .webp extension) - // - SVG (indicated with a .svg extension) - string filename = 2; + // A reference to the actual thumbnail image. + ReferencedImageDto referenced_image = 2; // The RGB background color to be shown behind the thumbnail image. Note that this is given in // RGB888 format, following local endianness (which is automatically handled by protobuf). There @@ -37,6 +31,24 @@ message ThumbnailDto { uint32 background_color_rgb = 3; } +// Represents an image that may be referenced by various topic structures. +message ReferencedImageDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; + + // The name of the image file. This will never be a URL (and can always be expected to just be a + // filename). The image is stored in GCS static file storage and must be downloaded separately by + // the client. The client can expect that this image is immutable on the server. Further, the + // client can also assume that all images are one of four formats: + // - PNG (indicated with a .png extension) + // - WebP (indicated with a .webp extension) + // - SVG (indicated with a .svg extension) + // - SVGZ (indicated with a .svgz extension) + string filename = 1; + + // The size of the voiceover file, in bytes. + uint32 file_size_bytes = 2; +} + // Represents a list of images that may be referenced by various topic structures. message ReferencedImageListDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = IMAGE_PROTO_VERSION; @@ -44,7 +56,6 @@ message ReferencedImageListDto { // The version defining the internal structure of this message. org.oppia.proto.v1.versions.ImageProtoVersion proto_version = 1; - // The list of filenames of all the images in the list. See the 'filename' field in Thumbnail for - // specifics on the expected values of these filenames. - repeated string referenced_image_filenames = 2; + // The list of referenced images contained in the list. + repeated ReferencedImageDto referenced_images = 2; } diff --git a/org/oppia/proto/v1/structure/languages.proto b/org/oppia/proto/v1/structure/languages.proto index c1b50a1..1c242c3 100644 --- a/org/oppia/proto/v1/structure/languages.proto +++ b/org/oppia/proto/v1/structure/languages.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; +import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; @@ -64,35 +65,54 @@ message SubtitledTextDto { // representation of this text. This ID is unique in its local context (e.g. a 'State' for // subtitled texts used within states). string content_id = 2; - - // The user-readable HTML/plain text content (which may be in Unicode). This is expected to always - // be in English, and in situations where non-English variants are desired the content ID should - // be matched to a language-specific translation (see WrittenTranslations for details). - string text = 3; } -// Represents a group of voiceovers that correspond to subtitled texts in a particular content -// context (such as a revision card or a 'State' in an exploration). -message RecordedVoiceoversDto { +// Represents all localizations of a particular activity (like an exploration or topic) for all +// supported languages of that activity. See ContentLocalizationDto for more details on the specific +// content included. +message ContentLocalizationsDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; // The version defining the internal structure of this message. org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; - // A list of mappings from language to voiceover content mappings (see the message's documentation - // for specifics on the latter). - repeated VoiceoverContentMappingDto voiceover_content_mapping = 2; + // The default mapping (including the language that the activity was originally created in). This + // contains the base strings and images of the activity that will be used as fallbacks if there + // are no corresponding localizations, as per the behavior of the client. + ContentLocalizationDto default_mapping = 2; + + // A list of mappings from language to content localization mappings (see the message's + // documentation for specifics on the latter). A missing mapping indicates no localization support + // for the corresponding language. + repeated ContentLocalizationDto localizations = 3; } -// Represents a mapping of SubtitledText content IDs to voiceovers for a particular language. -message VoiceoverContentMappingDto { +// Represents a language-specific localization of a top-level activity (like an exploration or a +// topic). This message is meant to contain all of the necesary data to fully localize that specific +// activity to the specified language. The mapping will also only contain localizations for that +// specific activity, and not any referenced ones (e.g. the topic itself but not its subtopics). +message ContentLocalizationDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; + // The language corresponding to this mapping. - LanguageType language = 1; + LanguageType language = 2; + + // The mapping of SubtitledText content IDs to their corresponding localized text representations. + map localizable_text_content_mapping = 3; // The mapping of SubtitledText content IDs to their corresponding voiceover files. - map voiceover_content_mapping = 2; + map voiceover_content_mapping = 4; + + // The thumbnail that should be used for this activity when it's viewed in the mapping's + // corresponding language. This field's absence indicates that the default thumbnail should be + // used. + ThumbnailDto thumbnail = 5; + + // The list of images localized to this mapping (within content). + ReferencedImageListDto localized_image_list = 6; } // Represents an audio file that, when played, reads out content text in a particular language. @@ -114,63 +134,38 @@ message VoiceoverFileDto { float duration_secs = 3; } -// Represents a group of written translations that correspond to subtitled texts in a particular -// content context (such as a revision card or a 'State' in an exploration). -message WrittenTranslationsDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - - // The version defining the internal structure of this message. - org.oppia.proto.v1.versions.LanguageProtosVersion protos_version = 1; - - // A list of mappings from language to written translation content mappings (see the message's - // documentation for specifics on the latter). - repeated WrittenTranslationContentMappingDto translation_language_mapping = 2; -} - -// Represents a mapping of SubtitledText content IDs to written translations for a particular -// language. -message WrittenTranslationContentMappingDto { - option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - - // The language corresponding to this mapping. - LanguageType language = 1; - - // The mapping of SubtitledText content IDs to their corresponding written translations. - map translation_content_mapping = 2; -} - -// Represents a single textual translation of specific content text in a particular language. -message WrittenTranslationDto { +// Represents a textual representation of specific content text in a particular language. +message LocalizableTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The data format of the source material for this translation. + // The data format of the source material for this localization. oneof data_format { - // Indicates that this translation corresponds to a single piece of text. - WrittenTranslatableTextDto translatable_text = 1; + // Indicates that this localization corresponds to a single piece of text. + SingleLocalizableTextDto single_localizable_text = 1; - // Indicates that this translation corresponds to a list of translated texts. - SetOfWrittenTranslatableTextDto set_of_translatable_text = 2; + // Indicates that this localization corresponds to a list of texts. + SetOfLocalizableTextDto set_of_localizable_text = 2; } } -// Represents the translation of a single text string (which may be either plain text or HTML, and -// is generally expected to potentially contain Unicode characters). -message WrittenTranslatableTextDto { +// Represents the localization of a single text string (which may be either plain text or HTML, and +// should always be expected to potentially contain Unicode characters). +message SingleLocalizableTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The human-readable translated string. - string translation = 1; + // TODO: Add support for fully structured HTML (to ensure proper RTE & structure validation and versioning). Also, differentiate between HTML & non-HTML. + // The human-readable and localized text. + string text = 1; } -// Represents a set of translated strings. As indicated in WrittenTranslatableText, each string may -// be either plain text or HTML, and generally can be expected to contain Unicode characters. +// Represents a set of localized strings. As indicated in SingleLocalizableTextDto, each string may +// be either plain text or HTML, and can contain Unicode characters. // -// Note that while the list of translated strings roughly corresponds to the original source -// material (i.e. the default, untranslated content strings specified directly in SubtitledText), -// neither the order nor the length are expected to exactly match. -message SetOfWrittenTranslatableTextDto { +// Note that there are no guarantees of the length or order of each element of the set to correspond +// to localizations of this same text in other languages. +message SetOfLocalizableTextDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = LANGUAGE_PROTOS_VERSION; - // The list of human-readable translated strings. - repeated string translations = 1; + // The list of human-readable localized strings. + repeated string text = 1; } diff --git a/org/oppia/proto/v1/structure/objects.proto b/org/oppia/proto/v1/structure/objects.proto index b7a4c32..d417c0e 100644 --- a/org/oppia/proto/v1/structure/objects.proto +++ b/org/oppia/proto/v1/structure/objects.proto @@ -5,8 +5,12 @@ package org.oppia.proto.v1.structure; option java_package = "org.oppia.proto.v1.structure"; option java_multiple_files = true; -// TODO: split up this proto into rule-spec based objects & update the versions accordingly. -// Anything not typed to rule inputs should go into the correct file with the correct versions. +// TODO: Figure out how to cleanly organize and version this file's protos. Some are specific to +// rule inputs, some are used as solution answers, and some can correspond to both. Perhaps +// structures should be duplicated such that there are distinct answer & input proto files, with +// all protos versioned by the state proto structure version. This probably has the cleaner typing +// even if it is slightly duplicative. That being said, some core structures could easily be +// isolated and shared (such as fractions & normalized point). More thought is needed here. // Proto message representing a single fraction or mixed number. message FractionDto { @@ -66,11 +70,9 @@ message RatioExpressionDto { // replacement strings for a different language can be found in the WrittenTranslations structure of // the containing State. message TranslatableSetOfNormalizedStringDto { - // The content ID corresponding to this set of normalized strings. + // The content ID corresponding to this set of normalized strings where the activity's + // translations should include a list of translated strings corresponding to this content ID. string content_id = 1; - - // The set of normalized strings to be translated as a whole. - repeated string normalized_strings = 2; } // Proto representing an image that is overlaid with labeled regions. @@ -85,13 +87,13 @@ message ImageWithRegionsDto { // Proto representing a labeled region of the image. message LabeledRegionDto { // The name of the region's label. - string label = 3; + string label = 1; // The type of the region. oneof region_type { // A rectangle that is normalized so that its boundary coordinates are within the range [0,1], // where 0 corresponds to one end of the image and 1 to the other. - NormalizedRectangle2dDto normalized_rectangle_2d = 1; + NormalizedRectangle2dDto normalized_rectangle_2d = 2; } // Proto representing a 2D rectangle defined using normalized coordinates relative to the image. diff --git a/org/oppia/proto/v1/structure/question.proto b/org/oppia/proto/v1/structure/question.proto index ee04927..d644bfc 100644 --- a/org/oppia/proto/v1/structure/question.proto +++ b/org/oppia/proto/v1/structure/question.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/structure/state.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; @@ -33,6 +33,42 @@ message QuestionDto { // The version of the contents of this question. uint32 content_version = 5; - // The list of all images that are included within SubtitledText subfields of this question. - ReferencedImageListDto referenced_image_list = 6; + // The default localized text, images, and voiceovers of this question. + ContentLocalizationDto default_localization = 6; } + +// Represents a localized language pack corresponding to both a single question and a single +// language. +message QuestionLanguagePackDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = QUESTION_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.QuestionProtoVersion proto_version = 1; + + // The ID of the pack. + LocalizedQuestionIdDto id = 2; + + // The language-specific localized text, images, and voiceovers of this question. + ContentLocalizationDto localization = 3; + + // The version of the pack's contents (e.g. specific translations). + uint32 content_version = 4; +} + +// Represents the identifier for a localized question, either indicating the question's default +// language, or referencing a language pack for the question. +message LocalizedQuestionIdDto { + // This proto message type is shared among multiple protos, so it has no direct migration pathway. + // Changes here should be carefully done in a way that does not break compatibility or assumptions + // across all relevant proto versions, or the proto should be duplicated according to whichever + // proto requires alterations. + option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + // The ID of the question. + string question_id = 1; + + // The language being localized either as the default for the question, or provided by a language + // pack. + LanguageType language = 2; +} + diff --git a/org/oppia/proto/v1/structure/revision_card.proto b/org/oppia/proto/v1/structure/revision_card.proto index c04e8cd..6179e0b 100644 --- a/org/oppia/proto/v1/structure/revision_card.proto +++ b/org/oppia/proto/v1/structure/revision_card.proto @@ -2,7 +2,6 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/image.proto"; import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; @@ -25,23 +24,35 @@ message RevisionCardDto { // The structured ID of the subtopic corresponding to this revision card. SubtopicPageIdDto id = 2; - // The human-readable title of the revision card. This is expected to be in English. - string title = 3; + // The localizable title of the revision card. + SubtitledTextDto title = 3; // The main content of this revision card. SubtitledTextDto content = 4; - // The recorded voiceovers for SubtitledText subfields of this revision card. - RecordedVoiceoversDto recorded_voiceovers = 5; + // The default localized text, images, and voiceovers of this revision card. + ContentLocalizationDto default_localization = 5; - // The written translations for SubtitledText subfields of this revision card. - WrittenTranslationsDto written_translations = 6; + // The version of the revision card's contents. + uint32 content_version = 6; +} + +// Represents a localized language pack corresponding to both a single revision card and a single +// language. +message RevisionCardLanguagePackDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = REVISION_CARD_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.RevisionCardProtoVersion proto_version = 1; - // The thumbnail image for this revision card. - ThumbnailDto thumbnail = 7; + // The ID of the pack. + LocalizedRevisionCardIdDto id = 2; - // The list of all images that are included within SubtitledText subfields of this revision card. - ReferencedImageListDto referenced_image_list = 8; + // The language-specific localized text, images, and voiceovers of this revision card. + ContentLocalizationDto localization = 3; + + // The version of the pack's contents (e.g. specific translations). + uint32 content_version = 4; } // Represents the identifier for a subtopic (which are tightly tied to specific topics). @@ -55,6 +66,23 @@ message SubtopicPageIdDto { // The ID of the topic that contains this subtopic. string topic_id = 1; - // The ID of the subtopic. - string subtopic_id = 2; + // The index-based ID of the subtopic. + uint32 subtopic_index = 2; +} + +// Represents the identifier for a localized revision card, either indicating the revision card's +// default language, or referencing a language pack for the revision card. +message LocalizedRevisionCardIdDto { + // This proto message type is shared among multiple protos, so it has no direct migration pathway. + // Changes here should be carefully done in a way that does not break compatibility or assumptions + // across all relevant proto versions, or the proto should be duplicated according to whichever + // proto requires alterations. + option (org.oppia.proto.v1.versions.structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + + // The structured ID of the subtopic corresponding to the revision card. + SubtopicPageIdDto id = 1; + + // The language being localized either as the default for the revision card, or provided by a + // language pack. + LanguageType language = 2; } diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index 025cf36..78d2562 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -27,12 +27,6 @@ message StateDto { // The interaction of the state (which must be interacted with by the learner in order to // proceed). InteractionInstanceDto interaction = 3; - - // The recorded voiceovers for SubtitledText subfields of this state. - RecordedVoiceoversDto recorded_voiceovers = 4; - - // The translations of SubtitledText subfields of this state. - WrittenTranslationsDto written_translations = 5; } // Represents an instance of a single interaction within a state. Note that interactions are @@ -636,11 +630,11 @@ message NumericInputInstanceDto { // Corresponds to the creator-specified inclusive lower bound for comparison against the // user's answer. - double inputLowerInclusive = 1; + double input_lower_inclusive = 1; // Corresponds to the creator-specified inclusive upper bound for comparison against the // user's answer. - double inputUpperInclusive = 2; + double input_upper_inclusive = 2; } // Represents a rule spec for checking whether an answer is equal to a creator-specified value @@ -650,10 +644,10 @@ message NumericInputInstanceDto { // Corresponds to the creator-specified tolerance to consider when matching against the user's // answer. - double inputTolerance = 1; + double input_tolerance = 1; // Corresponds to the creator-specified value to compare against the user's answer. - double inputComparedValue = 2; + double input_compared_value = 2; } } } @@ -815,7 +809,7 @@ message DragAndDropSortInputInstanceDto { // Specifies whether items can be allowed at the same position in the list (i.e. linked or // unlinked). - bool allowMultipleItemsInSamePosition = 2; + bool allow_multiple_items_in_same_position = 2; } // Represents the specific solution available to instances of the drag and drop sort input @@ -1152,7 +1146,7 @@ message AlgebraicExpressionInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; IsEquivalentToSpecDto is_equivalent_to = 3; } @@ -1238,7 +1232,7 @@ message MathEquationInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; IsEquivalentToSpecDto is_equivalent_to = 3; } @@ -1324,7 +1318,7 @@ message NumericExpressionInputInstanceDto { oneof rule_type { MatchesExactlyWithSpecDto matches_exactly_with = 1; - MatchesUpToTrivialManipulationsSpecDto matches_upTo_trivial_manipulations = 2; + MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; IsEquivalentToSpecDto is_equivalent_to = 3; } diff --git a/org/oppia/proto/v1/structure/topic_summary.proto b/org/oppia/proto/v1/structure/topic_summary.proto index 0760ce5..ea38f85 100644 --- a/org/oppia/proto/v1/structure/topic_summary.proto +++ b/org/oppia/proto/v1/structure/topic_summary.proto @@ -2,7 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.structure; -import "org/oppia/proto/v1/structure/image.proto"; +import "org/oppia/proto/v1/structure/languages.proto"; import "org/oppia/proto/v1/versions/structure_versions.proto"; option java_package = "org.oppia.proto.v1.structure"; @@ -27,23 +27,95 @@ message DownloadableTopicSummaryDto { // The ID of the topic. string id = 2; - // The human-readable name of the topic. This is expected to be in English. - string name = 3; + // The localizable name of the topic. + SubtitledTextDto name = 3; - // The human-readable description of the topic. This is expected to be in English. - string description = 4; + // The localizable description of the topic. + SubtitledTextDto description = 4; - // The list of stories available to play in the topic corresponding to this sumamry. + // The list of stories available to play in the topic corresponding to this summary. repeated StorySummaryDto story_summaries = 5; - // The list of subtopics available in the topic corresponding to this sumamry. + // The list of subtopics available in the topic corresponding to this summary. repeated SubtopicSummaryDto subtopic_summaries = 6; - // The thumbnail image corresponding to this topic. - ThumbnailDto thumbnail = 7; - // The version of this topic's contents. - uint32 content_version = 8; + uint32 content_version = 7; + + // IDs of topics that should be completed before this topic is suggested to the user. This list + // may change over time, but it is expected to be relatively stable. + repeated string prerequisite_topic_ids = 8; + + // The localized text, images, and voiceovers of this topic summary. + ContentLocalizationsDto localizations = 9; + + // A list of all skills referenced by the topic represented by this summuary (including in + // rich-text). + repeated SkillSummaryDto referenced_skills = 10; +} + +// Represents the summary of a topic that hasn't yet been released for users. This summary is meant +// to provide as much detail as possible for the indication of a future topic release to be +// meaningful and useful to the user (including a name, description, and estimated release +// time frame). +message UpcomingTopicSummaryDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.TopicSummaryProtoVersion proto_version = 1; + + // The ID of the topic. + string id = 2; + + // The localizable name of the topic. + SubtitledTextDto name = 3; + + // The localizable description of the topic. + SubtitledTextDto description = 4; + + // The approximated estimation for when this topic will be available for download. + ReleaseTimeEstimation release_time_estimation = 5; + + // Anticipated prerequisite topics that will need to be completed before this topic would be + // suggested. Note that this is not a stable list since the topic is still a work-in-progress. + // It's only meant to provide a preview to learners on what they may want to practice in + // preparation for this topic's release. + string anticipated_prerequisite_topic_ids = 6; + + // The localized text, images, and voiceovers of this topic summary. + ContentLocalizationsDto localizations = 7; + + // A variably granular representation of the estimated release time of a topic. The fields in this + // are provided in-order to provide a more granular estimate, and each subsequent field is + // relative to the previous field. + message ReleaseTimeEstimation { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; + + // The year that the topic is expected to be available to download. This value should always be + // provided for a valid estimation. A value of 0 indicates that the release date is not known + // for the topic. + int32 year = 1; + + // The quarter within the year above that the topic is expected to be available. This should + // always be a value within [0, 4] as each year has only 4 quarters. A value of 0 indicates that + // this estimation is not granular to quarters. This value is ignored if year is 0. + // + // Quarters follow the calendar year, that is, quarter 1 corresponds to January, February, and + // March. + int32 quarter = 2; + + // The month within the quarter defined above that the topic is expected to be available. This + // should always be a value within [0, 3] as each quarter hasb only 3 months. A value of 0 + // indicates that this estimation is not granular to months. This value is ignored if quarter is + // 0. + int32 month = 3; + + // The day within the month defined above that the topic is expected to be available. This + // should always be a value within [0, 31], though the upper bound will depend on the specific + // month estimated for release. A value of 0 indicates that this estimation is not granular to + // days. This value is ignored if month is 0. + int32 day = 4; + } } // Represents the summary of a story that can be played within a particular topic. Stories aim to @@ -55,20 +127,20 @@ message StorySummaryDto { // The ID of the story. string id = 1; - // The human-readable title of the story. This is expected to be in English. - string title = 2; + // The localizable title of the story. + SubtitledTextDto title = 2; - // The human-readable description of the story. This is expected to be in English. - string description = 3; - - // The thumbnail image of the story. - ThumbnailDto thumbnail = 4; + // The localizable description of the story. + SubtitledTextDto description = 3; // The summaries of all chapters in this story. - repeated ChapterSummaryDto chapters = 5; + repeated ChapterSummaryDto chapters = 4; // The version of this story's contents. - uint32 content_version = 6; + uint32 content_version = 5; + + // The localized text, images, and voiceovers of this story summary. + ContentLocalizationsDto localizations = 6; } // Represents the summary of a single chapter within a story of a topic. Each chapter corresponds to @@ -76,12 +148,12 @@ message StorySummaryDto { message ChapterSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; - // The thumbnail image for this chapter. - ThumbnailDto thumbnail = 1; + // The localizable title of the chapter. This is expected to exactly match, in content, the title + // of the exploration associated to this chapter. + SubtitledTextDto title = 1; - // The human-radable title of the chapter. This is expected to be in English, and is expected to - // exactly match the title of the exploration associated to this chapter. - string title = 2; + // A localizable explanation for what the learner is expected to learn when playing this chapter. + SubtitledTextDto description = 2; // The ID of the exploration to which this ChapterSummary is associated. string exploration_id = 3; @@ -89,6 +161,9 @@ message ChapterSummaryDto { // The version of this chapter's contents. This is expected to always match the exploration // associated to this chapter. uint32 content_version = 4; + + // The localized text, images, and voiceovers of this chapter summary. + ContentLocalizationsDto localizations = 5; } // Represents the summary of a subtopic (that is, a group of skills logically organized within a @@ -96,11 +171,14 @@ message ChapterSummaryDto { message SubtopicSummaryDto { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; - // The index of the subtopic (within its correspnoding topic). + // The index of the subtopic (within its correspnoding topic). This helps to indicate the + // subtopic's relative pedagogical order within the topic (that is, it should occur before topics + // with greater indexes). Indexes will never be shared between subtopics in the same topic. uint32 index = 1; - // The list of all skills grouped by this subtopic. - repeated SkillSummaryDto skill_summaries = 2; + // The list of IDs for skills grouped by this subtopic. Each of these skills should be included in + // the subtopic's containing topic summary list of skills. + repeated string referenced_skill_ids = 2; // The version of this subtopic's contents. uint32 content_version = 3; @@ -113,9 +191,12 @@ message SkillSummaryDto { // The ID of the skill. string id = 1; - // The human-readable name of the skill. This is expected to be in English. - string name = 2; + // The localizable name of the skill. + SubtitledTextDto name = 2; // The version of this skill's contents. uint32 content_version = 3; + + // The localized text, images, and voiceovers of this skill summary. + ContentLocalizationsDto localizations = 4; } diff --git a/org/oppia/proto/v1/versions/BUILD.bazel b/org/oppia/proto/v1/versions/BUILD similarity index 52% rename from org/oppia/proto/v1/versions/BUILD.bazel rename to org/oppia/proto/v1/versions/BUILD index 102377e..4898f43 100644 --- a/org/oppia/proto/v1/versions/BUILD.bazel +++ b/org/oppia/proto/v1/versions/BUILD @@ -3,21 +3,22 @@ Libraries that define proto versions used by API & structural protos for client- compatibility. """ -load("@rules_proto//proto:defs.bzl", "proto_library") +load("//defs:defs.bzl", "define_buildifier_tests", "oppia_proto_library") -proto_library( +oppia_proto_library( name = "versions_proto", srcs = [ "api_versions.proto", "structure_versions.proto", ], - strip_import_prefix = "", # Strip the default file prefix so that it may be redefined. - import_prefix = "org/oppia/proto/v1/versions", # Make directory prefix match declared package. + relative_parent_dir_path = "org/oppia/proto/v1/versions", visibility = [ "//:api_visibility", "//:proto_impl_visibility", ], deps = [ - "@com_google_protobuf//:descriptor_proto", + "@com_google_protobuf//:descriptor_proto", ], ) + +define_buildifier_tests() diff --git a/org/oppia/proto/v1/versions/api_versions.proto b/org/oppia/proto/v1/versions/api_versions.proto index e10c154..06bf2c7 100644 --- a/org/oppia/proto/v1/versions/api_versions.proto +++ b/org/oppia/proto/v1/versions/api_versions.proto @@ -13,6 +13,9 @@ option java_multiple_files = true; extend google.protobuf.MessageOptions { // Defines the version type corresponding to an API proto. ApiProtoVersionType api_proto_version_type = 2000; + + // Indicates the actual structure version. This should only be used in version protos. + uint32 latest_api_proto_version = 2001; } // Represents the version of the proto structures for topic list request & response messages. This @@ -21,6 +24,7 @@ extend google.protobuf.MessageOptions { // See the README for details on how these versions are meant to be used. message TopicListRequestResponseProtoVersion { option (api_proto_version_type) = UNVERSIONED_API_PROTO; + option (latest_api_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -32,6 +36,7 @@ message TopicListRequestResponseProtoVersion { // See the README for details on how these versions are meant to be used. message TopicContentRequestResponseProtoVersion { option (api_proto_version_type) = UNVERSIONED_API_PROTO; + option (latest_api_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; diff --git a/org/oppia/proto/v1/versions/structure_versions.proto b/org/oppia/proto/v1/versions/structure_versions.proto index 42e1e2c..c890725 100644 --- a/org/oppia/proto/v1/versions/structure_versions.proto +++ b/org/oppia/proto/v1/versions/structure_versions.proto @@ -7,16 +7,19 @@ import "google/protobuf/descriptor.proto"; option java_package = "org.oppia.proto.v1.versions"; option java_multiple_files = true; -// Custom options. Note that these do not actually enforce semantics--they're -// just hints. Implementation code is expected to define the actual versioning -// semantics. See the README for more details. +// Custom options. Note that these do not actually enforce semantics--they're just hints. +// Implementation code is expected to define the actual versioning semantics. See the README for +// more details. extend google.protobuf.MessageOptions { // Defines the version type corresponding to a structure proto. StructureProtoVersionType structure_proto_version_type = 1000; + + // Indicates the actual structure version. This should only be used in version protos. + uint32 latest_structure_proto_version = 1001; } extend google.protobuf.EnumOptions { // Defines the version type corresponding to a structure enum. - StructureProtoVersionType structure_enum_version_type = 1001; + StructureProtoVersionType structure_enum_version_type = 1002; } // Represents the version of the proto structures for topic summary messages. This structure is @@ -25,6 +28,7 @@ extend google.protobuf.EnumOptions { // See the README for details on how these versions are meant to be used. message TopicSummaryProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -36,6 +40,7 @@ message TopicSummaryProtoVersion { // See the README for details on how these versions are meant to be used. message RevisionCardProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -47,6 +52,7 @@ message RevisionCardProtoVersion { // See the README for details on how these versions are meant to be used. message ConceptCardProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -58,6 +64,7 @@ message ConceptCardProtoVersion { // See the README for details on how these versions are meant to be used. message ExplorationProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -69,6 +76,7 @@ message ExplorationProtoVersion { // See the README for details on how these versions are meant to be used. message QuestionProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -84,6 +92,7 @@ message QuestionProtoVersion { // See the README for details on how these versions are meant to be used. message StateProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -98,6 +107,7 @@ message StateProtoVersion { // See also the README for details on how these versions are meant to be used. message LanguageProtosVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; @@ -110,6 +120,7 @@ message LanguageProtosVersion { // See the README for details on how these versions are meant to be used. message ImageProtoVersion { option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; // The numeric version corresponding to the containing proto's structure. uint32 version = 1; diff --git a/repo/BUILD b/repo/BUILD index d3b683c..9d122a3 100644 --- a/repo/BUILD +++ b/repo/BUILD @@ -3,3 +3,7 @@ Reusable Starlark macros for setting up both the local Bazel WORKSPACE, and also workspaces for importing the protos defined in this project. See the README for more details on importing this repository in other Bazel workspaces. """ + +load("//defs:defs.bzl", "define_buildifier_tests") + +define_buildifier_tests() diff --git a/repo/deps.bzl b/repo/deps.bzl index e65d5a8..651c997 100644 --- a/repo/deps.bzl +++ b/repo/deps.bzl @@ -5,83 +5,38 @@ instructions in the README for more details. """ load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") - -# Note to developers: Please keep this dict sorted by key to make it easier to find dependencies. -_DEPENDENCY_VERSIONS = { - "rules_python": { - "sha": "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b", - "url": "https://github.com/bazelbuild/rules_python/releases/download/{0}/rules_python-{0}.tar.gz", - "version": "0.3.0", - }, - "com_google_protobuf": { - "sha": "c6003e1d2e7fefa78a3039f19f383b4f3a61e81be8c19356f85b6461998ad3db", - "strip_prefix": "protobuf-{0}", - "url": "https://github.com/protocolbuffers/protobuf/archive/v{0}.tar.gz", - "version": "3.17.3", - }, - "rules_proto": { - # Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a - # specific commit hash. - "sha": "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208", - "strip_prefix": "rules_proto-{0}", - "url": "https://github.com/bazelbuild/rules_proto/archive/{0}.tar.gz", - "version": "97d8af4dc474595af3900dd85cb3a29ad28cc313", - }, - "rules_java": { - "sha": "220b87d8cfabd22d1c6d8e3cdb4249abd4c93dcc152e0667db061fb1b957ee68", - "url": "https://github.com/bazelbuild/rules_java/releases/download/{0}/rules_java-{0}.tar.gz", - "version": "0.1.1", - }, -} +load("//repo:versions.bzl", "MAVEN_DEPENDENCY_VERSIONS") def _setUpHttpArchiveDependency(name): - metadata = _DEPENDENCY_VERSIONS[name] - sha = metadata["sha"] - strip_prefix = metadata.get("strip_prefix") - url = metadata["url"] - version = metadata["version"] - - formatted_strip_prefix = strip_prefix.format(version) if not (strip_prefix == None) else None - - http_archive( - name = name, - urls = [url.format(version)], - sha256 = sha, - strip_prefix = formatted_strip_prefix, - ) - -def _setUpPython(): - _setUpHttpArchiveDependency(name = "rules_python") + metadata = MAVEN_DEPENDENCY_VERSIONS[name] + sha = metadata["sha"] + strip_prefix = metadata.get("strip_prefix") + url = metadata["url"] + version = metadata["version"] -def _setUpProtobuf(): - _setUpHttpArchiveDependency(name = "com_google_protobuf") + formatted_strip_prefix = strip_prefix.format(version) if not (strip_prefix == None) else None -def _setUpRulesProto(): - _setUpHttpArchiveDependency(name = "rules_proto") - -def _setUpRulesJava(): - _setUpHttpArchiveDependency(name = "rules_java") + http_archive( + name = name, + urls = [url.format(version)], + sha256 = sha, + strip_prefix = formatted_strip_prefix, + ) def initializeDepsForWorkspace(): - """ - Loads the dependencies needed to be able to build the Oppia proto API project. - - Note that this must be called after loading in this deps file, for example: - - load("//repo:deps.bzl", "initializeDepsForWorkspace") - initializeDepsForWorkspace() + """ + Loads the dependencies needed to be able to build the Oppia proto API project. - Note also that toolchains may need to be set up after loading this dependencies (see - toolchains.bzl). - """ - # Set up Python (as a prerequisite dependency for Protobuf). - _setUpPython() + Note that this must be called after loading in this deps file, for example: - # Set up proto & its toolchain. - _setUpProtobuf() + load("//repo:deps.bzl", "initializeDepsForWorkspace") + initializeDepsForWorkspace() - # Set up rules_proto to allow defining proto libraries. - _setUpRulesProto() + Note also that toolchains may need to be set up after loading this dependencies (see + toolchains.bzl). + """ - # Set up rules_java to enable the Java proto & Java proto lite rules. - _setUpRulesJava() + # Set up all dependencies (the order doesn't matter here since it's just downloading corresponding + # HTTP archives). + for dependency_name in MAVEN_DEPENDENCY_VERSIONS.keys(): + _setUpHttpArchiveDependency(name = dependency_name) diff --git a/repo/toolchains.bzl b/repo/toolchains.bzl index 0d818cf..7c37053 100644 --- a/repo/toolchains.bzl +++ b/repo/toolchains.bzl @@ -4,24 +4,44 @@ proto API project (such as for cases when another Bazel workspace depends on thi importing instructions in the README for more details. """ -load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") +load("@bazel_gazelle//:deps.bzl", "gazelle_dependencies") +load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps") +load("@io_bazel_rules_go//go:deps.bzl", "go_register_toolchains", "go_rules_dependencies") +load("@rules_buf//buf:repositories.bzl", "rules_buf_dependencies", "rules_buf_toolchains") load("@rules_java//java:repositories.bzl", "rules_java_dependencies", "rules_java_toolchains") +load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies", "rules_proto_toolchains") +load("//repo:versions.bzl", "BUF_VERSION", "GO_VERSION") def initializeToolchainsForWorkspace(): - """ - Initializes the toolchains needed to be able to build the Oppia proto API project. + """ + Initializes the toolchains needed to be able to build the Oppia proto API project. + + Note that this must be called after loading in this toolchains file, for example: + + load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") + initializeToolchainsForWorkspace() + + Note also that this can't be called until the dependencies themselves are loaded (see deps.bzl). + """ + + # Set up the toolchains for rules_go. + go_rules_dependencies() + go_register_toolchains(version = GO_VERSION) + + # Set up the dependencies for Gazelle. + gazelle_dependencies() - Note that this must be called after loading in this toolchains file, for example: + # Set up the toolchains for rules_proto. + rules_proto_dependencies() + rules_proto_toolchains() - load("//repo:toolchains.bzl", "initializeToolchainsForWorkspace") - initializeToolchainsForWorkspace() + # Set up the toolchains for rules_java. + rules_java_dependencies() + rules_java_toolchains() - Note also that this can't be called until the dependencies themselves are loaded (see deps.bzl). - """ - # Set up the toolchains for rules_proto. - rules_proto_dependencies() - rules_proto_toolchains() + # Set up the toolchains for rules_buf. + rules_buf_dependencies() + rules_buf_toolchains(version = "v%s" % BUF_VERSION) - # Set up the toolchains for rules_java. - rules_java_dependencies() - rules_java_toolchains() + # Set up the dependencies for proto build tools (including Buildifier). + protobuf_deps() diff --git a/repo/versions.bzl b/repo/versions.bzl new file mode 100644 index 0000000..1855087 --- /dev/null +++ b/repo/versions.bzl @@ -0,0 +1,56 @@ +""" +Defines third-party dependencies and their versions. +""" + +# Note to developers: Please keep this dict sorted by key to make it easier to find dependencies. +MAVEN_DEPENDENCY_VERSIONS = { + "bazel_gazelle": { + "sha": "de69a09dc70417580aabf20a28619bb3ef60d038470c7cf8442fafcf627c21cb", + "url": "https://github.com/bazelbuild/bazel-gazelle/releases/download/v{0}/bazel-gazelle-v{0}.tar.gz", + "version": "0.24.0", + }, + "com_github_bazelbuild_buildtools": { + "sha": "ae34c344514e08c23e90da0e2d6cb700fcd28e80c02e23e4d5715dddcb42f7b3", + "strip_prefix": "buildtools-{0}", + "url": "https://github.com/bazelbuild/buildtools/archive/refs/tags/{0}.tar.gz", + "version": "4.2.2", + }, + "com_google_protobuf": { + "sha": "c6003e1d2e7fefa78a3039f19f383b4f3a61e81be8c19356f85b6461998ad3db", + "strip_prefix": "protobuf-{0}", + "url": "https://github.com/protocolbuffers/protobuf/archive/v{0}.tar.gz", + "version": "3.17.3", + }, + "io_bazel_rules_go": { + "sha": "8e968b5fcea1d2d64071872b12737bbb5514524ee5f0a4f54f5920266c261acb", + "url": "https://github.com/bazelbuild/rules_go/releases/download/v{0}/rules_go-v{0}.zip", + "version": "0.28.0", # Last version compatible with Bazel 4.0.0. + }, + "rules_buf": { + "sha": "523a4e06f0746661e092d083757263a249fedca535bd6dd819a8c50de074731a", + "strip_prefix": "rules_buf-{0}", + "url": "https://github.com/bufbuild/rules_buf/archive/refs/tags/v{0}.zip", + "version": "0.1.1", + }, + "rules_java": { + "sha": "220b87d8cfabd22d1c6d8e3cdb4249abd4c93dcc152e0667db061fb1b957ee68", + "url": "https://github.com/bazelbuild/rules_java/releases/download/{0}/rules_java-{0}.tar.gz", + "version": "0.1.1", + }, + "rules_proto": { + # Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a + # specific commit hash. + "sha": "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208", + "strip_prefix": "rules_proto-{0}", + "url": "https://github.com/bazelbuild/rules_proto/archive/{0}.tar.gz", + "version": "97d8af4dc474595af3900dd85cb3a29ad28cc313", + }, + "rules_python": { + "sha": "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b", + "url": "https://github.com/bazelbuild/rules_python/releases/download/{0}/rules_python-{0}.tar.gz", + "version": "0.3.0", + }, +} + +BUF_VERSION = "1.14.0" +GO_VERSION = "1.17.2" From 7219d373c524363c5c7ce58fee8455590ea82679 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 2 Jun 2023 19:15:07 -0700 Subject: [PATCH 44/51] Clarify calendar documentation. --- .../proto/v1/structure/topic_summary.proto | 29 ++++++++++--------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/org/oppia/proto/v1/structure/topic_summary.proto b/org/oppia/proto/v1/structure/topic_summary.proto index ea38f85..c6c0357 100644 --- a/org/oppia/proto/v1/structure/topic_summary.proto +++ b/org/oppia/proto/v1/structure/topic_summary.proto @@ -91,29 +91,30 @@ message UpcomingTopicSummaryDto { message ReleaseTimeEstimation { option (org.oppia.proto.v1.versions.structure_proto_version_type) = TOPIC_SUMMARY_PROTO_VERSION; - // The year that the topic is expected to be available to download. This value should always be - // provided for a valid estimation. A value of 0 indicates that the release date is not known - // for the topic. + // The year that the topic is expected to be available to download, per the Gregorian calendar. + // This value should always be provided for a valid estimation. A value of 0 indicates that the + // release date is not known for the topic. int32 year = 1; - // The quarter within the year above that the topic is expected to be available. This should - // always be a value within [0, 4] as each year has only 4 quarters. A value of 0 indicates that - // this estimation is not granular to quarters. This value is ignored if year is 0. + // The quarter within the year above that the topic is expected to be available, per the + // Gregorian calendar. This should always be a value within [0, 4] as each year has only 4 + // quarters. A value of 0 indicates that this estimation is not granular to quarters. This value + // is ignored if year is ignored. // // Quarters follow the calendar year, that is, quarter 1 corresponds to January, February, and // March. int32 quarter = 2; - // The month within the quarter defined above that the topic is expected to be available. This - // should always be a value within [0, 3] as each quarter hasb only 3 months. A value of 0 - // indicates that this estimation is not granular to months. This value is ignored if quarter is - // 0. + // The month within the quarter defined above that the topic is expected to be available, per + // the Gregorian calendar. This should always be a value within [0, 3] as each quarter has only + // 3 months. A value of 0 indicates that this estimation is not granular to months. This value + // is ignored if quarter is ignored. int32 month = 3; - // The day within the month defined above that the topic is expected to be available. This - // should always be a value within [0, 31], though the upper bound will depend on the specific - // month estimated for release. A value of 0 indicates that this estimation is not granular to - // days. This value is ignored if month is 0. + // The day within the month defined above that the topic is expected to be available, per the + // Gregorian calendar. This should always be a value within [0, 31], though the upper bound will + // depend on the specific month estimated for release. A value of 0 indicates that this + // estimation is not granular to days. This value is ignored if month is ignored. int32 day = 4; } } From 8bcb631e43134afd78b47c9bdd13c076eb550cac Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Fri, 2 Jun 2023 19:18:21 -0700 Subject: [PATCH 45/51] Add support for Nigerian Pidgin. --- org/oppia/proto/v1/structure/languages.proto | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/structure/languages.proto b/org/oppia/proto/v1/structure/languages.proto index 1c242c3..395790a 100644 --- a/org/oppia/proto/v1/structure/languages.proto +++ b/org/oppia/proto/v1/structure/languages.proto @@ -37,7 +37,7 @@ enum LanguageType { // Corresponds to the macaronic language Hinglish which combines Hindi and English. This // corresponds to a generic 'Hinglish' which combines localisms from different areas, but is not - // predominantly tied to a particular region. + // predominately tied to a particular region. HINGLISH = 4; // Corresponds to a regional Portuguese that's primarily used in Brazil. @@ -45,6 +45,9 @@ enum LanguageType { // Corresponds to general Swahili (that is, not particularly regionally tied). SWAHILI = 6; + + // Corresponds to the creole language Naija that's predominately used in Nigeria. + NIGERIAN_PIDGIN = 7; } // Represents a block of (subtitled) text. This structure is used for content strings so that they From 4ea008bd2685e4126169ee029381ea6301b2e133 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Sat, 3 Jun 2023 15:47:08 -0700 Subject: [PATCH 46/51] Add possibility for absence (rather than failure). Requests should be allowed to fail gracefully. Also, fixes a small formatting inconsistency. --- org/oppia/proto/v1/api/android.proto | 5 +++++ org/oppia/proto/v1/structure/objects.proto | 1 - 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 9da82bd..da786ab 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -287,6 +287,11 @@ message TopicContentResponseDto { // expected to fail rather than a particular item within the response). bool skipped_from_failure = 3; + // The presence of thise value indicates that the request doesn't correspond to an actual + // structure for the given ID/version. Note that the value of the field itself doesn't matter, + // just its presence. + bool skipped_does_not_exist = 14; + // The result is a requested topic summary. org.oppia.proto.v1.structure.DownloadableTopicSummaryDto topic_summary = 4; diff --git a/org/oppia/proto/v1/structure/objects.proto b/org/oppia/proto/v1/structure/objects.proto index d417c0e..7be0622 100644 --- a/org/oppia/proto/v1/structure/objects.proto +++ b/org/oppia/proto/v1/structure/objects.proto @@ -49,7 +49,6 @@ message ListOfSetsOfTranslatableHtmlContentIdsDto { // Proto representing a 2D point for the ImageRegion interaction type. message NormalizedPoint2dDto { - // Relative x-coordinate of the point within the image. This lies within the range [0, 1] and // measures horizontal distance (with the left boundary of the image as the origin). double x = 1; From cb3434ea5ac6b3f5d50b9eec1b533373e952ac6e Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 20 Mar 2024 19:11:08 +0000 Subject: [PATCH 47/51] Add support for classroom summaries. This is in preparation for introducing support in the Android app for multiple learning classrooms. --- org/oppia/proto/v1/api/android.proto | 6 ++++ org/oppia/proto/v1/structure/BUILD | 1 + org/oppia/proto/v1/structure/classroom.proto | 33 +++++++++++++++++++ .../v1/versions/structure_versions.proto | 15 +++++++++ 4 files changed, 55 insertions(+) create mode 100644 org/oppia/proto/v1/structure/classroom.proto diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index da786ab..c99abb2 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package org.oppia.proto.v1.api; +import "org/oppia/proto/v1/structure/classroom.proto"; import "org/oppia/proto/v1/structure/concept_card.proto"; import "org/oppia/proto/v1/structure/exploration.proto"; import "org/oppia/proto/v1/structure/languages.proto"; @@ -102,6 +103,11 @@ message TopicListResponseDto { // A list of all topics that will be available to the client to install in the future. repeated FutureTopicDto future_topics = 3; + // A list of available classrooms for learning. Clients may opt to only show topics that + // correspond to a classroom, and it is possible for a topic to belong to more than one classroom + // simultaneously. + repeated org.oppia.proto.v1.structure.ClassroomDto classrooms = 4; + // A topic that's available to & compatible with the local client. message AvailableTopicDto { option (org.oppia.proto.v1.versions.api_proto_version_type) = TOPIC_LIST_REQUEST_RESPONSE_PROTO_VERSION; diff --git a/org/oppia/proto/v1/structure/BUILD b/org/oppia/proto/v1/structure/BUILD index 75e0622..bbd8e19 100644 --- a/org/oppia/proto/v1/structure/BUILD +++ b/org/oppia/proto/v1/structure/BUILD @@ -7,6 +7,7 @@ load("//defs:defs.bzl", "define_buildifier_tests", "oppia_proto_library") oppia_proto_library( name = "structure_proto", srcs = [ + "classroom.proto", "concept_card.proto", "exploration.proto", "image.proto", diff --git a/org/oppia/proto/v1/structure/classroom.proto b/org/oppia/proto/v1/structure/classroom.proto new file mode 100644 index 0000000..37a7fd2 --- /dev/null +++ b/org/oppia/proto/v1/structure/classroom.proto @@ -0,0 +1,33 @@ +syntax = "proto3"; + +package org.oppia.proto.v1.structure; + +import "org/oppia/proto/v1/structure/languages.proto"; +import "org/oppia/proto/v1/versions/structure_versions.proto"; + +option java_package = "org.oppia.proto.v1.structure"; +option java_multiple_files = true; + +// Represents the summary of a classroom whose topics are available to the user to view and possibly +// download. Note tha topics are considered the primary top-level learning 'unit' even though +// they're organized categorically into classrooms. +message ClassroomDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = CLASSROOM_PROTO_VERSION; + + // The version defining the internal structure of this message. + org.oppia.proto.v1.versions.ClassroomProtoVersion proto_version = 1; + + // The globally unique ID of the classroom. + string id = 2; + + // The localizable name of the classroom. + SubtitledTextDto name = 3; + + // The list of topics contained within this classroom. These topics do not have to be available + // for the local client to download (instead, this list will comprise of all published or planned + // topics for the classroom). + repeated string topic_ids = 4; + + // The localized text, images, and voiceovers of this classroom. + ContentLocalizationsDto localizations = 5; +} diff --git a/org/oppia/proto/v1/versions/structure_versions.proto b/org/oppia/proto/v1/versions/structure_versions.proto index c890725..7c29ba0 100644 --- a/org/oppia/proto/v1/versions/structure_versions.proto +++ b/org/oppia/proto/v1/versions/structure_versions.proto @@ -126,6 +126,18 @@ message ImageProtoVersion { uint32 version = 1; } +// Represents the version of the proto structures for classrooms. This structure is never expected +// to change. +// +// See the README for details on how these versions are meant to be used. +message ClassroomProtoVersion { + option (structure_proto_version_type) = UNVERSIONED_STRUCTURE_PROTO; + option (latest_structure_proto_version) = 1; + + // The numeric version corresponding to the containing proto's structure. + uint32 version = 1; +} + // Represents the type of versioning corresponding to a structure proto message. enum StructureProtoVersionType { // The default version type (that is, unspecified and not corresponding to any versioning scheme). @@ -159,4 +171,7 @@ enum StructureProtoVersionType { // Indicates that the proto is bound by ImageProtoVersion. IMAGE_PROTO_VERSION = 9; + + // Indicates that the proto is bound by ClassroomProtoVersion. + CLASSROOM_PROTO_VERSION = 10; } From 87422ba4ddcf70c324646e779c6c0e45f2718c84 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Wed, 20 Mar 2024 22:31:16 +0000 Subject: [PATCH 48/51] Add new version to compatibility context. --- org/oppia/proto/v1/api/android.proto | 3 +++ 1 file changed, 3 insertions(+) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index c99abb2..84ebec3 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -392,6 +392,9 @@ message ClientCompatibilityContextDto { // The latest proto version for images that the client can support. org.oppia.proto.v1.versions.ImageProtoVersion image_proto_version = 10; + + // The latest proto version for classrooms that the client can support. + org.oppia.proto.v1.versions.ClassroomProtoVersion classroom_proto_version = 11; } // Details about a versione dstructure that's compatible with the local client. This can be used From 98d31221cc4ae9aa8e8ebcda60ea5e690520453f Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 27 May 2024 14:43:12 -0700 Subject: [PATCH 49/51] Update rules_proto. This ensures that an older zlib isn't referenced per https://github.com/bazelbuild/rules_proto/pull/117. --- repo/versions.bzl | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/repo/versions.bzl b/repo/versions.bzl index 1855087..37aed8f 100644 --- a/repo/versions.bzl +++ b/repo/versions.bzl @@ -38,12 +38,10 @@ MAVEN_DEPENDENCY_VERSIONS = { "version": "0.1.1", }, "rules_proto": { - # Note that rules_proto doesn't have any shipped versions, so the workspace needs to pin to a - # specific commit hash. - "sha": "602e7161d9195e50246177e7c55b2f39950a9cf7366f74ed5f22fd45750cd208", + "sha": "e017528fd1c91c5a33f15493e3a398181a9e821a804eb7ff5acdd1d2d6c2b18d", "strip_prefix": "rules_proto-{0}", - "url": "https://github.com/bazelbuild/rules_proto/archive/{0}.tar.gz", - "version": "97d8af4dc474595af3900dd85cb3a29ad28cc313", + "url": "https://github.com/bazelbuild/rules_proto/archive/refs/tags/{0}.tar.gz", + "version": "4.0.0-3.20.0", }, "rules_python": { "sha": "934c9ceb552e84577b0faf1e5a2f0450314985b4d8712b2b70717dc679fdc01b", From 9cf993ea0b798a67b3faa21c690c30b9027fb371 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Mon, 27 May 2024 14:45:01 -0700 Subject: [PATCH 50/51] Fix documentation typo. --- org/oppia/proto/v1/api/android.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/org/oppia/proto/v1/api/android.proto b/org/oppia/proto/v1/api/android.proto index 84ebec3..b60f1e9 100644 --- a/org/oppia/proto/v1/api/android.proto +++ b/org/oppia/proto/v1/api/android.proto @@ -293,7 +293,7 @@ message TopicContentResponseDto { // expected to fail rather than a particular item within the response). bool skipped_from_failure = 3; - // The presence of thise value indicates that the request doesn't correspond to an actual + // The presence of this value indicates that the request doesn't correspond to an actual // structure for the given ID/version. Note that the value of the field itself doesn't matter, // just its presence. bool skipped_does_not_exist = 14; From f6d167c5de636edf941e366dc9a6ca6b2bf20e89 Mon Sep 17 00:00:00 2001 From: Ben Henning Date: Sat, 28 Dec 2024 23:19:37 +0000 Subject: [PATCH 51/51] Add structural support for NumberWithUnits. --- org/oppia/proto/v1/structure/objects.proto | 28 ++++++++- org/oppia/proto/v1/structure/state.proto | 72 +++++++++++++++++++++- 2 files changed, 96 insertions(+), 4 deletions(-) diff --git a/org/oppia/proto/v1/structure/objects.proto b/org/oppia/proto/v1/structure/objects.proto index 7be0622..2ce0ff9 100644 --- a/org/oppia/proto/v1/structure/objects.proto +++ b/org/oppia/proto/v1/structure/objects.proto @@ -76,7 +76,6 @@ message TranslatableSetOfNormalizedStringDto { // Proto representing an image that is overlaid with labeled regions. message ImageWithRegionsDto { - // The filepath of the image, which will be prefixed with '[exploration_id]/assets'. string image_file_path = 1; @@ -108,3 +107,30 @@ message ImageWithRegionsDto { } } } + +// Proto representing a physical quantity with both a numeric and unit component. The numeric +// portion can take different forms (such as a real number or a fraction). +message NumberWithUnitsDto { + // The units corresponding to this physical quantity. There may be more than one, e.g. m/s^2 would + // have one unit of m^1 and a second unit of s^-2. + repeated Unit units = 1; + + // The type of number represented in this physical quantity. + oneof type { + // Corresponds to a real numeric quantity, such as 10.5m/s^2. + double real = 2; + + // Corresponds to a fractional numeric quantity, such as 1/2m/s^2. + FractionDto fraction = 3; + } + + // Represents either a multiplication or division unit, such as m/s. + message Unit { + // The human-readable name of the unit, such as 'm' for meters. + string label = 1; + + // The exponent of the unit, such as '1' for 'm' in 2m, or '-2' for 's' in 2m/s^2. The sign of + // this exponent indicates whether this unit is a multiplied or divided unit. + int32 exponent = 2; + } +} diff --git a/org/oppia/proto/v1/structure/state.proto b/org/oppia/proto/v1/structure/state.proto index 78d2562..4bb4a18 100644 --- a/org/oppia/proto/v1/structure/state.proto +++ b/org/oppia/proto/v1/structure/state.proto @@ -97,6 +97,9 @@ message InteractionInstanceDto { // An interaction for inputting numeric equations. NumericExpressionInputInstanceDto numeric_expression_input = 12; + // An interaction for inputting numbers with units attached. + NumberWithUnitsInputInstanceDto number_with_units_input = 14; + // An interaction that represents the end of an exploration and takes no direct user input other // than navigating away from the exploration. This is not used in question play sessions. EndExplorationInstanceDto end_exploration = 13; @@ -1147,7 +1150,7 @@ message AlgebraicExpressionInputInstanceDto { MatchesExactlyWithSpecDto matches_exactly_with = 1; MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; - + IsEquivalentToSpecDto is_equivalent_to = 3; } @@ -1233,7 +1236,7 @@ message MathEquationInputInstanceDto { MatchesExactlyWithSpecDto matches_exactly_with = 1; MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; - + IsEquivalentToSpecDto is_equivalent_to = 3; } @@ -1319,7 +1322,7 @@ message NumericExpressionInputInstanceDto { MatchesExactlyWithSpecDto matches_exactly_with = 1; MatchesUpToTrivialManipulationsSpecDto matches_up_to_trivial_manipulations = 2; - + IsEquivalentToSpecDto is_equivalent_to = 3; } @@ -1355,6 +1358,69 @@ message NumericExpressionInputInstanceDto { } } +// Represents an interaction where the user can input an numeric answer with units. Details: +// - Answer type: NumberWithUnits +// - Has a default outcome: yes +// - Has support for showing hints: yes +// - Has support for showing a solution: yes +message NumberWithUnitsInputInstanceDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The default outcome for this interaction. + OutcomeDto default_outcome = 1; + + // The hints corresponding to this interaction. + repeated HintDto hints = 2; + + // The answer groups for this interaction. + repeated AnswerGroupDto answer_groups = 3; + + // The solution corresponding to this interaction. + SolutionDto solution = 4; + + message AnswerGroupDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the answer group. + BaseAnswerGroupDto base_answer_group = 1; + + // The list of all rules to match for this answer group. + repeated RuleSpecDto rule_specs = 2; + } + + message RuleSpecDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + oneof rule_type { + IsEqualToSpecDto is_equal_to = 1; + + IsEquivalentToSpecDto is_equivalent_to = 2; + } + + message IsEqualToSpecDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + NumberWithUnitsDto number_with_units = 1; + } + + message IsEquivalentToSpecDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + NumberWithUnitsDto number_with_units = 1; + } + } + + message SolutionDto { + option (org.oppia.proto.v1.versions.structure_proto_version_type) = STATE_PROTO_VERSION; + + // The base properties of the solution. + BaseSolutionDto base_solution = 1; + + // The correct answer for this interaction that should be shown to the user. + NumberWithUnitsDto correct_answer = 2; + } +} + // Represents an interaction where the user has reached the end of the exploration, and has the // choice to navigate away from it. Details: // - Answer type: none (N/A since no answers are submitted for this interaction)